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Preface 


The Introduction to F'MS gives an overview of the Forms Management Sys- 
tem and provides exercises for using many of the features of FMS. After 
reading this manual, you should be able to use the rest of the FMS docu- 
mentation and the FMS software easily. 


This manual does the following: 


e Introduces FMS and describes its components 


e Walks you through the Sample Application, a program provided in the 
FMS kit to demonstrate most of the FMS features 


e Shows you how to create a subset of the Sample Application 


e Describes some of the more advanced features of FMS and shows you how 
to use them 


e Gives hints on designing good forms 


Chapter Summary 


Chapter 1, Overview of FMS, introduces FMS and gives a general descrip- 
tion of its components. The chapter tells how to use this manual and also 
provides a reading path for the FMS document set. 


Chapter 2, Running the Sample Application Program, gives you an oppor- 
tunity to see an FMS application. Specific capabilities of FMS are pointed 
out as you run the Sample Application. 


Chapter 3, Creating Forms, is an exercise in designing, creating, and test- 
ing two forms used in the Sample Application. 


Chapter 4, Creating a Form Library, describes how to create a library for 
the forms that you created in Chapter 3 and how to obtain and use form 
descriptions of those forms. 


Chapter 5, Writing an Application, is an exercise in coding a subset of the 
Sample Application. The exercise uses the two forms you created in Chap- 
ter 3. In Chapter 5, you use the Form Driver. 
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Chapter 6, Compiling, Linking, and Running an Application, describes how 
to compile, link, and run the subset application created in Chapter 5. The 
steps outlined here are described in general terms so that you can apply 
them to your FMS applications. 


Chapter 7, Programming Features, describes some of the more advanced 
features of FMS, such as scrolling, Named Data, indexing, and user action 
routines. 


Chapter 8, Advice to New Users, describes a successful form and explains 
how to incorporate good form design into your forms. 


The Glossary defines FMS terms used throughout the FMS document set. 


Intended Audience 
This manual is directed to two groups of readers: 


e Those who want a general overview of FMS Version 2 


e Those who have had experience with FMS Version 1 software and wish to 
learn about FMS Version 2 


Readers should be familiar with BASIC and DCL. 


Documentation Conventions 


Uppercase letters In commands and examples, indicate that the user 
types the item exactly as shown. 


Brackets [ ] Indicate that the item is optional. 
Red print Indicates what the user types. 
CTRL/x Indicates that you simultaneously press the key la- 


beled CTRL and another key. 


GOLD x Indicates that you press the PF1 key before you press 
the second key. 


Unless specified otherwise, you terminate commands by pressing the 
RETURN key. 


Chapter 1 
Overview of FMS 


We are all familiar with forms in our everyday lives — tax forms, employ- 
ment forms, insurance forms, and so on. Most of these forms contain the 
same two types of information. First, the forms have information already 
printed on them — titles, headings, descriptions of items to be filled in, 
and instructions. Second, the forms have blank spaces for the information 
to be filled in by the user of the form. 


Video forms created with DIGITAL’s VAX-11 FMS Forms Management 
System look very similar to the paper forms described above. Like paper 
forms, video forms contain information that never changes; this back- 
ground text is protected against modification by both the program and the 
terminal user. The areas of the form that can be changed — by the appli- 
cation program, by the terminal user, or by both — are known as fields. 
On the surface, then, video forms are like paper forms. 


When we look further, however, we find that VAX-11 FMS adds many 
properties to video forms that have no counterpart in paper forms. The 
interactive nature of FMS allows data entered by the operator to be vali- 
dated as it is entered to ensure that letters are not typed where numbers 
are required, that required fields are not left blank, and so on. Further- 
more, FMS provides techniques for additional validation and processing of 
entered data to be done by the application program. Therefore, the terminal 
user will see a single smooth interaction with the computer system, with all 
errors being caught at the earliest possible moment. Other features that 
FMS presents to the terminal user include the scrolling of portions of the 
form to show more lines of information than can fit on the screen at once, 
the display of help information whenever the operator presses the HELP 
key, and a variety of visual effects ranging from double-high, double-wide 
characters to forms overlaid on other forms. 


Forms as Seen by the Programmer 


To the application developer, forms contain much more than background 
text and fields. Some attributes, such as the name of a help form, pertain to 


the entire form; other attributes, such as right justification, pertain to indi- 
vidual fields. Another part of the form definition allows the application 
developer to specify that the cursor should move from field to field in a 
sequence other than the normal left-to-right, top-to-bottom sequence. Fi- 
nally, the programmer can specify the names of subroutines either to be 
automatically invoked by FMS upon completion of fields or when function 
keys are depressed or to supplement the standard FMS handling of help 
requests. In addition to the parameters that can be stored with the form 
and passed to these subroutines, FMS provides additional parameter stor- 
age for other parameters that can be read by the program from the form 
description during program execution. 


FMS provides support for the following languages: 
e VAX-11 BASIC 

e VAX-11 BLISS 

e VAX-11 C 

e VAX-11 COBOL 

e VAX-11 FORTRAN 

e VAX-11 PASCAL 

e VAX-11 PL/I 


1.1 FMS Components 


To create forms and to write and run a program, you use the following 
components: 


¢ Form Editor 

e Form Language Translator 
e Form Librarian 

e Form Driver 

e Form Tester 


e Form Application Aids 


1.1.1 Form Editor 


The Form Editor lets you design, modify, test, and store forms. When you 
use the Form Editor, you design and modify forms interactively; your 
screen always shows the current state of the form you are working on. You 
can use special keypad and keyboard functions to specify video display 
characteristics such as boldface type or reverse video for different parts of 
the.form. To help operators, you can include on-line help — short explana- 
tions about parts of the form and about the whole form. 
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When designing forms, you assign names to the forms and to data that will 
be entered or displayed when the application runs. The VAX-11 FMS Utili- 
ties Reference Manual describes the Form Editor in detail. 


1.1.2 Form Language Translator 


The Form Language Translator converts form descriptions that you have 
created with a text editor, using Form Language statements, into binary 
forms. The Form Language has all the capabilities of the Form Editor, but 
lets you create forms on any terminal, video or hard copy. If you prefer a 
language-like method of preparing forms, you can use the Form Language. 
The Form Translator can also convert form descriptions produced by the 
Form Application Aids into binary forms. The VAX—11 FMS Utilities Ref- 
erence Manual describes the Form Language and Form Language Transla- 
tor in detail. 


1.1.3 Form Librarian 


The Form Librarian allows you to create library files in which you can 
insert, extract, or delete forms. For more information on the Form Librar- 
ian, see the VAX-—11 FMS Utilities Reference Manual. 


1.1.4 Form Driver 


The Form Driver is a set of subroutines that your program uses to access 
the forms that you created with the Form Editor or with the Form Lan- 
guage. FMS applications access forms by means of Form Driver calls that 
you include in the source program. All Form Driver calls refer to specific 
forms and data within forms by names that you assign during form editing. 
When the FMS application runs, the Form Driver does the following: 


e Attaches the operator’s terminal and establishes I/O channels to the ap- 
propriate form library and the terminal 


e Displays forms and accepts operator input 


e Refers to data specifications contained in the form to check that the oper- 
ator input is valid 


e Responds to operator requests for help by displaying help text associated 
with the form being processed 


e Displays or erases data in the forms 


The VAX-—11 FMS Form Driver Reference Manual describes the Form 
_ Driver and its calls in detail. 


1.1.5 Sample Application 


The Sample Application (SAMP) is a demonstration program in the FMS 
distribution kit. The Sample Application shows most of the features FMS 
provides and is a learning tool. All the examples and exercises in this 
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manual are taken from the Sample Application. You will run the Sample 
Application in Chapter 2. The forms you create in Chapter 3, Creating 
Forms, are from the Sample Application. In Chapter 5, you will write a 
subset of the Sample Application, using the forms that you created earlier. 
1.1.6 Form Tester 


The Form Tester lets you test a form without first having to put the form in 
a library or write an application program. The Form Tester uses the Form 
Driver to display your form and to perform I/O operations. When using the 
Form Tester, you see the form as it will appear when the application runs. 
You can enter data into fields and check the validation of the data entered. 
1.1.7 Form Application Aids 

The Form Application Aids allows you to do the following: 

¢ Convert binary forms to object modules for use as memory-resident forms 
e Provide form descriptions | 


e Create vector modules for user action routines 


© Create COBOL data definition files and DATATRIEVE domain definition 
files 


Using the Form Application Aids, you can produce four types of form de- 
scriptions: 


¢ Form Language statements that are suitable for translation into binary 
forms 


¢ Form images either with or without escape sequences 


e Field data structure descriptions that are compatible with COBOL and 
DATATRIEVE applications that use FMS 


e Brief summaries of form data 


1.2 FMS Application Development 
The development of an FMS application involves three processes: 
e Creating forms and form libraries 
e Writing the application’s source program 


e Writing the application’s user action routine(s) 


This section discusses each process, showing how and where each compo- 
nent of FMS is involved with the development of the entire application. 
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Before beginning work on these processes, you must plan the application. 
This step, often the most important, deserves a great deal of attention. You 
must first analyze the task that the FMS application is to perform and 
determine what types of data the application will be working with. When 
you plan your FMS application, it helps to know what kinds of data the 
operator is expected to enter at the terminal. Next, plan your forms based 
on that data. You can then prepare the source code to handle the forms that 
you will need for your application. Keep in mind the operator’s skills and 
the computer system on which the application will be running. You can 
provide on-line help for the operator as he or she runs the application. 


The sections that follow provide details on each step of the FMS application 
development cycle. 


Create Forms and Form Libraries 


Using the Form Editor, lay out the forms. Because the Form Editor is 
interactive, you can plan your forms and modify them as you create them. 
Sketching them beforehand is unnecessary. Arrange the text and video 
features of the forms so that the forms are orderly and pleasing to the eye. 
When you are done laying out the forms, you can test the forms to verify 
that only the desired types of data will be accepted. 


If you are creating forms with the Form Language, use a text editor to 
enter the statements that make up the form, called a source form descrip- 
tion. Use the Form Translator to convert the source form description into a _ 
binary form description, which is suitable for inserting into a Form Library 
or for linking with the application’s object module as a memory-resident 
form. You can use the Form Tester to test this binary form description. The 
Form Tester displays the form as if it were being displayed by the applica- 
tion on the screen during run time. You can try entering data into the form 
to verify that it accepts and displays data as intended. Source form descrip- 
tions, binary form descriptions, and memory-resident forms are discussed 
in detail later in this manual. 


Store Forms in a Form Library 


After you have created and tested your forms, use the Form Librarian to 
store them in a library file. During run time, the application program 
accesses forms from the form library unless you have made the forms mem- 
ory resident. 


Create a User Action Routine Vector Module 


If your application has user action routines (UARs),.use the Form Applica- 
tion Aids to create a UAR vector module. UAR vector modules are dis- 
cussed in Chapter 7. 
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Create Memory-Resident Forms 


If you want to use memory-resident forms in your application, use the Form 
Application Aids to convert the forms in your form library into memory- 
resident format. Note that you do not need to create memory-resident forms 
directly from the form library. That is, you can create a memory-resident 
form immediately after it has been created by the Form Editor or the Form 
Translator. However, all memory-resident forms used in an application can 
be linked only as a single file. So if you want to make several forms mem- 
ory resident, create them directly from the form library. 


Obtain a Directory of the Form Library 


You can use the Form Application Aids to list the contents of a form library 
file. This listing shows all the forms in a form library. 


Obtain a Form Description 


You can use the Form Application Aids to get a form description in source 
code. Form descriptions are particularly useful as hard-copy reference for 
forms. Form descriptions are discussed in Chapter 4. (Note that the source 
form description can be input to the Form Translator to create a binary 
form, suitable for insertion into a form library or for use as a memory- 
resident form.) 


Obtain COBOL Data Definition and DATATRIEVE 
Domain Definition Files 


You can use the Form Application Aids to create a COBOL data declaration 
file for the forms in your form library if your application is written in 
VAX-—11 COBOL. The COBOL data declaration file can be compiled with 
the source file for your application. Some editing to this file may be neces- 
sary. 


Figure 1-1 is a flowchart that shows the development of forms and 
libraries. 


Write the Application’s Source Program 


Referring to the form descriptions produced by the Form Application Aids, 
write the source code for your application, using a text editor. Refer to the 
form descriptions for the correct names of the forms and fields in the form. 
Include Form Driver calls in your source program to display forms and to 
perform I/O transfers among the terminal, the form library, and the appli- 
cation. 
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Form Development Cycle 
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Compile the Application 


Compile the application’s source program to produce an object module. If 
your application is written in VAX—11 COBOL, compile the COBOL data 
definition file with your source program. 


Figure 1—2 shows the steps in the development of the main program of an 
FMS application. 
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Figure 1-2: Source Application Development Cycle 
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Write User Action Routines 


Using a text editor, write any user action routines that your application 
uses. UARs can exist in files by themselves or in the same file as the main 
program. Typically, application-specific UARs exist in the same file as the 
main program. General-purpose UARs are often compiled separately and 
are kept in object libraries. 


Note that if you use UARs in your application, you must create a UAR 
vector module. Vector modules are described in Chapter 7. 


Figure 1-3 shows the steps in the development of UARs. 
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Figure 1-3: UAR Development Cycle 
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Link the Application 

You link the following modules: 

e Main program object module 

© User action routine object module 
e User action routine vector module 
e Any memory-resident forms 


e Form Driver 


Figure 1-4 is a flowchart that shows the linking of an FMS application. 


Memory: UAR vector UAR object 
resident module module 
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Form library 


Figure 1-4: Linking of an FMS Application 
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1.3 Reading Path for the FMS Document Set 
The VAX-11 FMS document set includes the following manuals: 
e VAX-11 FMS Installation Guide and Release Notes 
e VAX-11 FMS Mini-Reference 
¢ Introduction to VAX—11 FMS 
e VAX-11 FMS Utilities Reference Manual 
e VAX-11 FMS Form Driver Reference Manual 
© VAX-11 FMS Language Interface Manual 
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Figure 1—5 shows the reading path for this manual set. The manuals are 
described below. 
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Figure 1-5: FMS Document Reading Path 


VAX-11 FMS Installation Guide and Release Notes contains installation 
procedures for FMS on VAX/VMS, a description of the Installation Verifi- 
cation Procedure, and information not included elsewhere in the document 
set. This manual describes the Form Upgrade Utility, which converts Ver- 
sion 1 forms and libraries to Version 2 forms and libraries. 


This manual is intended for the person responsible for installing FMS and 
for upgrading any applications to Version 2. 


VAX-11 FMS Mini-Reference provides concise reference material for the 
contents of the other manuals. This manual also contains a diagram of the 
Form Editor keypad and a synopsis of compiling, linking, and running FMS 
applications. 


This manual is intended for all users of FMS. 

Introduction to VAX—11 FMS introduces Version 2 of FMS and its utilities. 
The reader gains experience in creating forms, writing an FMS application, 
and using the Form Librarian, the Form Editor, and the Form Driver. This 


manual also contains a glossary of FMS terms. 


This manual is intended for all users of FMS. 


Overview of FMS 1-11 


VAX~—11 FMS Utilities Reference Manual describes the following FMS utili- 
ties: 


e Form Editor 

e Form Language Translator 
e Form Librarian 

e Form Application Aids 


© Form Tester 


The manual includes examples of how to use these utilities. 


This manual is intended for the application programmer and the person 
responsible for creating and maintaining forms and libraries. 


VAX-11 FMS Form Driver Reference Manual describes the function of the 
Form Driver and the Form Driver calls and explains how to use them. 
Programming techniques are discussed to help you with your FMS applica- 
tions. 


This manual is intended for the application programmer. 


VAX-11 FMS Language Interface Manual describes the FMS interface to 
the languages that FMS supports. A chapter is provided for each language 
that FMS supports, with examples in that language taken from the Sample 
Application. The Sample Application presented at the end of each chapter 
is written in the language of that chapter. 


This manual is intended for the application programmer. 
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Chapter 2 
Running the Sample Application Program 


As you read this chapter, you will: 
e Run the Sample Application program, a checking account program 
e See what the FMS features allow you to do 


e Get a feel for being an operator as you work with FMS forms 


Before continuing, check with your system manager to make sure that the 
FMS distribution kit has been installed on your system. 


2.1 Setting Up Your Terminal 


You can run FMS programs on any VT100 or VT100-compatible terminal. 
Before running the Sample Application, do the following: 


1. Type the following command at the terminal on which you plan to run 
the Form Editor: 


$ SET TERMINAL/ INQUIRE 
In response, the VMS system identifies the terminal you are using. 


2. To see what the operating system knows about your terminal, type the 
following command: 


$ SHOW TERMINAL 


In response, the system displays a list of your terminal’s characteris- 
tics. Check to see that the list includes either the ANSI_-CRT or the 
VT52 characteristic. 


3. Check to see if the list obtained from the SHOW TERMINAL command 
includes the advanced video characteristic. If so indicated, your termi- 
nal has the advanced video option (AVO). If your terminal does not 
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have AVO, the Sample Application as it appears on your screen will 
differ from what is shown in this manual. Specifically, a terminal with- 
out AVO: 


e Can show reverse video or underlining, but not both 


e Can display a maximum of 14 lines when set to a 132-column screen 
width 


Terminals with AVO can display the blink and bold attributes and 24 
lines when set to a 132-column screen width. 


2.2 Starting the Sample Application 
To start the Sample Application, enter the following commands: 


$ RUN FMSSEXAMPLES:SAMP 


The Sample Application displays the following image: 


Welcome to the FMS V2 


Sample Application Program (SAMP>) 


YOUR PERSONAL CHECKING ACCOUNT 


[For instructions, press HELP (the PFe key). 
To continue, press RETURN. 





What you see is a form. This form identifies the application. You are told to 
press the PF2 key for on-line help and the RETURN key to continue. The 
HELP key is on the keypad to the right of the keyboard. 


2-2 Running the Sample Application Program 


Press HELP. The following image appears. 


Help for the FMS V2 Sample Application Program 
The FMS Sample Application program (SAMP) serves two purposes: 


1. It tests the Form Driver and is part of the Installation Verifi- 
cation Procedure. 


It shows how to use FMS. The Sample Application is available in 
each language supported by FMS, and the documentation cites 
many examples that are from SAMP. 


The application does not claim to show the best way of doing everything. 


Rather, it shows ways that things can be done with FIRS. 


As you run the rest of SAMP, you can get help by pressing the PF2 key, which 
will be referred to as the HELP key. Repeated pressing of the key provides 

_ additional help until the message is displayed, "No help available.” If you 
press HELP now, you will see an explanation of the keys used in FMS. 


For nore help, press HELP. 
To continue, press RETURN. 





This image is a help form. This help form describes the Sample Application 
and tells how to get help while the program is running. If you press HELP 
again, you will see another form that gives general instructions for enter- 
ing data into forms and for moving the cursor from field to field. This 
second help form also tells you that you can press keypad period at any 
time to abort any procedure. If you press HELP again, a message appears 
at the bottom of the screen, saying that no more help is available. If you 
press HELP again, the first help form you saw appears. An FMS form can 
have any number of help forms associated with it. You will learn how to 
create help forms in Chapter 3. 


After you have seen all the help available with this form, press RETURN. 
The first form you saw, entitled Welcome to the FMS V2 Sample Applica- 
tion Program, will appear again. Press RETURN again. The following form 
appears. 
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Checking Account Nenu 


Choose option (1-5): A 
1 Exit 
2 Write a check 
3 Make a deposit 


View the check register 


For help, press HELP. 
To continue, press keypad 1-5. 


Show account data 





This form is a menu, a form from which you can select actions that the 
application can perform. The title of this form, Checking Account Menu, is 
in double-size characters and in reverse video. The second line of this form, 
Choose option (1—5):, is in double-wide characters. 


The cursor is located next to the caption Choose option (1—5):. The cursor is 
located in a field. In an FMS form, fields are used to display data or to 
accept and display data input by an operator. In the field shown above, the 
number 2 already appears. This number is the default for this field. If you 
do not specify a number, FMS will choose option 2. 


Press HELP. The following message appears at the bottom of the screen: 


Enter one of the numbers ls 29 3, 4+ or 5 


This help line gives you assistance for the field in which the cursor is 
positioned. 


Press HELP again. The help form that appears describes the menu’s op- 
tions. If you press HELP again, the second help form associated with the 
first form you saw appears. After you have examined the help forms associ- 
ated with the menu, return to the menu by pressing RETURN. 


Before entering an option number, type an alphabetic character. When you 
do, the terminal beeps, and a message is displayed on the bottom line of the 
screen. As the Sample Application displays a form, the Form Driver checks 
to see if input to a field is valid. If you try to enter an alphabetic character 


2-4 Running the Sample Application Program 


into a field that can accept only numbers, the Form Driver indicates that 
the input is invalid by signaling you with a beep and by displaying the 
following message: 


Numeric required 


Now type a 2-digit number. When you do, a message is displayed on the 
bottom line, indicating that the field is full. The Form Driver can also limit 
the number of characters that can be entered in a field. 


Select option 2, Write a check, by pressing keypad 2. (You can also press 
keyboard 2, followed by RETURN, to select option 2. If you receive the 
Fieldfull message, press DELETE; then type 2, followed by RETURN.) The 
following form appears: 


WRITE A CHECK 


Katherine M. Smith Number _ 8 

4 Hog Hill Rd. 

Townsend, AK 99999 Date: 47-SEP-82 
(800)555-1212 


Pay to §j Amount: $#3%, 4% 


Nena 


FIRST NATIONAL BANK Account 532 


Current Balance: $ 361.30 





The name and address on this form, in addition to other account data, were 
provided by an account data file supplied with the Sample Application. The 
cursor is located next to the caption Pay to. Before filling in this field, press 
HELP to see what help is available. 


The help form associated with this form tells you that you can fill in fields 
and that you can move the cursor forward to the next field by pressing TAB 
and backward to a previous field by pressing BACKSPACE. The help form 
also tells you that when you are satisfied with the entries you have made, 
you can press RETURN to enter the check into the check register. You can 
abort the check-writing process by pressing keypad period, which returns 
you to the menu. 
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(Note that the help form specifies that the keypad period key has been 
assigned a special function in the Sample Application. Assigning functions 
to keypad keys is a feature available to your FMS applications.) 


The Pay to field has the Response Required attribute. Before you finish 
filling in this field, press LINEFEED. Doing so deletes the contents of the 
field. You can move the cursor left or right within the field by pressing 
CHARBCK or CHARFWD, respectively. After filling in the Pay to field, 
press RETURN. The Form Driver signals you by beeping and displays the 
following message on the bottom line of the screen: 


Ineut required 


The cursor is now positioned in the next field, Amount. If you press RE- 
TURN, the terminal beeps, and a message is displayed at the bottom of the 
screen, indicating that input is required. 


Note that the cursor is positioned to the right of the Amount field. As you 
enter numbers in this field, they appear to the left of the cursor and are 
pushed to the left as you continue to type numbers. This field is right 
justified; that is, the operator can enter numbers as in a calculator or an 
electronic cash register. 


Now enter an alphabetic character into this field. The following message 
appears at the bottom of the screen: 


Numeric reauired 


Only numbers can be entered in this field. Fill in the next field, Memo, and 
press RETURN. Note that the current balance figure, shown below the 
check, is updated and that the following message appears at the bottom of 
the screen: 


Your check has been written and sent to the pPayee’s account, 
To return to menus Press Keypad period, 


To Print check into file "SAMPCH.DAT"» Press Keypad zero, 
To write another checks press RETURN. 


Now press RETURN or ENTER. Make out another check. This time, how- 
ever, make it out in an amount greater than the current balance. When you 
press RETURN, a message appears at the bottom of the screen, saying that 
you attempted to write a check that exceeds the current balance. Enter an 
appropriate amount and press RETURN. 


You can write another check if you wish, or you can return to the main 
menu by pressing keypad period. 
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When you return to the menu, select option 3, Make a deposit, by pressing 
keypad 3. The following form appears on the screen: 


MAKE A DEPOSIT 
Date: 17-SEP-82 


Current Balance $ 361.30 


Deposit $0000.00 
New Balance $ 


Heno: 





Take a moment to examine the form and read the available help. Now 
enter a deposit. Note that the cursor is positioned on the decimal point in 
this field. As you enter numbers, they are pushed to the left of the decimal 
point. This field has the Fixed Decimal attribute. If you type a period and 
then enter more numbers, they appear to the right of the decimal point. 


After you fill in the memo and press RETURN, a message appears, saying 
that the deposit has been made. 
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When you are through examining the Make a Deposit form, return to the 
menu and select option 4, View the check register, by pressing keypad 4. 
The following form appears on the screen: 


CHECK REGISTER —- THE ACCOUNT HISTORY 


Chk. Deposit Check New 
No. Date Check Payee or Deposit Meno Amount Amount Balance 


31-AUG-82 | Paycheck 


This Session: Starting Balance: $ 361.30 
Total Deposits: $ .0 
Total Checks: $ .0 
Current Balance: $ 361.30 


To scroll through the check register, press UPARROW or DOWNARROW. 
To return to the menu, press RETURN. 





This form shows the FMS scrolling feature. Scrolling enables you to display 
more lines than can fit on one screen. Look at the list in the check register. 
Each item in the list records information on a check written or a deposit 
made. Note the message at the bottom of the form: 


To scroll through the check registers press UPARROW and DOWNARROW, 
To return to the menus press RETURN, 


Now press DOWNLINE to scroll forward. The list of register items scrolls 
up one item. That is, the item that was at the top of the list has disap- 
peared, and a new item has appeared at the bottom of the list. 


Press DOWNLINE several times to scroll to the last item in the check 
register. When the last item is reached, the following message appears on 
the bottom of the screen: 


Last line of register 


Press UPLINE to get to the top of the check register. When you reach the 
top, a message appears, saying that the top of the check register has been 
reached. (Chapter 7 describes how scrolling was implemented in the Sam- 
ple Application.) 
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When you are through examining the check register, return to the menu 
and select option 5, Show Account Data, by pressing keypad 5. The follow- 
ing form appears on the screen: 


ACCOUNT DATA 


ACCOUNT NUMBER: Account opened: 


NAME Last: ES First:(EUCS Middle: xs 


Mg: Hos “il. Rd. 
State: Zip: 


Business: (0.0) bbs eeet 


Enter secret password to change the account data: fj 


To record new account data and return to the menu, press RETURN. 
To return to the menu without changing the data, press keypad period. 





This form requests a password to change the account data. Press HELP. 
The help line provides the password. Before entering the password, press 
HELP again to see a description of this form. The Sample Application re- 
quires that you enter the password in uppercase letters, as indicated in the 
help line. 


You can alter any of the data in the fields of this form, but these modifica- 
tions are not permanent, as explained in the help form. When you run the 
Sample Application again, this form will look the same as when you first 
ran the program. (This is how SAMP was designed; FMS does not restrict 
you from making permanent changes to any data base.) 


The password is an example of the FMS No Echo attribute. You can include 
this feature in your applications to provide a measure of protection. When- 
ever an operator enters data into a field with the No Echo attribute, the 
data goes to the application program, but does not appear on the screen. 


When you are through examining the Account Data form, you can return to 
the menu and exit by pressing keypad 1, or you can reexamine some of the 
forms. 
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2.3 Printing SAMPCH.DAT 


When you ran the Sample Application and wrote a check, you had the 
option of sending a check to the data file SAMPCH.DAT for subsequent 
printing. In this section, you will get a hard-copy listing of that data file. 
When you specify that you want a check sent to SAMPCH.DAT, the Sample 
Application sends SAMPCH.DAT to your main directory. 


To obtain a hard-copy listing of SAMPCH.DAT, type the following com 


mand: 


$ PRINT SAMPCH.DAT 


The following is a sample listing of SAMPCH.DAT: 


Katherine M. Smith 

1 Hos Hill Ra. 

Townsend, AK 99999 
(BOG) SSS-1212 


Pay to L. Martin 


Memo Roofing supplies 


FIRST NATIONAL BANK 


tee er eee eK eK 
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Chapter 3 


Creating Forms 


As you read this chapter, you will: 


e Learn how to set your terminal to run the Form Editor 


e Examine two forms from the Sample Application 


e Create two forms that appear in the Sample Application 


e Create a help form 


3.1 Setting Up Your Terminal 


You can use the Form Editor on a VT100 or a VT100-compatible terminal. 
Before running the Form Editor, do the following: 


1. Type the following command: 


$ SET TERMINAL/ INQUIRE 
In response, the VMS system identifies the terminal you are using. 


To see what the operating system knows about your terminal, type the 
following command: 


$ SHOW TERMINAL 


In response, the system displays a list of your terminal’s characteris- 
tics. Check to see that the list includes the DEC_CRT characteristic. 


Check to see if the list obtained from the SHOW TERMINAL command 
includes the advanced video characteristic. If so indicated, your termi- 
nal has the advanced video option (AVO). If your terminal does not 
have AVO, the Form Editor as it appears on your screen will differ from 
what is shown in this manual. Specifically, a terminal without AVO: 


e Can show reverse video or underlining, but not both 


e Display a maximum of 14 lines when set to a 132-column screen 
width 


Terminals with AVO can display the blink and bold attributes and 24 
lines when set to a 132-column screen width. 


3.2 Examining Two Forms from the Sample Application 


In Chapter 2, you ran the Sample Application from the FMS distribution 
kit. In this chapter, you will look more closely at two of the forms in that 
application program. 


First, rerun part of the Sample Application so that you can see the two 
forms again. As in Chapter 2, run the Sample Application by typing the 
following commands: 


$ RUN FMSSEXAMPLES:SAMP 


You will first examine the forms and then create them yourself. 


3.2.1 MENU Form 


After you see the form entitled Welcome to the FMS V2 Sample Application 
Program, press RETURN. The menu, entitled Checking Account Menu, 
appears. We will call this form MENU. 


In the MENU form shown below, the numbers above and to the left of the 
form are line and column indicators for the exact positions of fields and the 
background text. 


10 20 30 40 50 60 70 80 


Cpe Checking Account Menu 


Choose option (1-5): A+@® 


1 Exit 
2 Write a check 
3 Make a deposit 


View the check register 


For help, press HELP. 
To continue, press keypad 1-5. 


Show account data 
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MENU has the following design features: 


1. 


The form appears with white background and dark text. The form ap- 
pears in reverse video. 


The title, @, is centered at the top and has double-size characters. The 
title is in reverse video. 


This form’s only field,®, appears two lines below the title and is under- 
lined. When this form appears on the screen, a 2 is already in the field; 
the 2 is the default value for this field. This field, along with its caption, 
Choose Option (1-5): is centered on line 7 and has double-wide charac- 
ters. The caption is background text that identifies the field; that is, the 
field can be referred to as the Choose option field. 


More background text, ©, starts in column 27 in lines 9, 11, 13, 15, and 
17. 


The boxed background text in the bottom right of the form gives in- 
structions to the operator. 


Consider the purpose of MENU. The operator uses this form as a menu for 
selecting an action listed in the background,©. The operator types the 
number of the action to be taken. Only numbers in the range 1 to 5 are 
accepted. If the operator types a number outside that range or a nonnu- 
meric character, the Form Driver does not accept it, beeping the terminal 
and displaying an error message at the bottom of the screen. 


Press HELP. A message appears at the bottom of the screen,©. When you 
create this form, you will provide the help text that appears at the bottom 
of this form. 
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3.2.2 DEPOSIT Form 


After you have examined MENU on the screen, press keypad 3. The form 
entitled Make a Deposit appears. We will call this form DEPOSIT. The 
DEPOSIT form is shown below. 


(A) MAKE A DEPOSIT 


Date: 24-SEP-82 <i. 1 
Current Balance $ 361.530 <—«__________—- 2 
Deposit $0000%%h0 <____—____-- 3 


New Balance . 7 SSS 


Heno: ——— 5 





DEPOSIT has the following design features: 


1. The form appears with a white screen background and dark text, as in 
MENU. 


2. The title, @, is centered at the top of the screen and is in uppercase bold. 
The title starts in column 32. 


3. Field 1, with its caption, is to the right on the form. The caption Date: is 
in column 49 on line 3. 


4. Fields 2, 3, and 4, with their captions, appear below the title. These 
fields begin in column 42 on lines 5, 7, and 9. The captions Current 
Balance, Deposit, and New Balance begin in column 22 on lines 5, 7, 
and 9. 


5. Field 5 is underlined. The field’s caption, Memo, begins in line 12, col- 
umn 22. Field 5 spans columns 28 to 62, occupying 35 character spaces. 
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CHARBCK 







UPLINE DOWNLINE 








OVRSTRIK DELLINE 






“UNDELLIN 


INSERT 


SCROLL 





ALL PHASES 
RETURN Terminates display of current form pier cued 
(in Layout, moves cursor to next line) | UNSCROLL W UNDRAW 
DELETE Deletes previous character 
ENDSCROL DELCHR 
LINEFEED Deletes field contents (in Layout, moves 


cursor down one line in same column) 


TAB Moves cursor to next field (in Layout, 
moves cursor to next fixed tab stop) 


BACKSPACE Moves cursor to previous field (in Layout, 
moves cursor to previous character 






“BOTTOM: 









CENTER TSTPASTE 








pession) | cHRSET )\ DELEOL " ADJFLD 
GOLD Q Reverses current error signaling mode = 
SELECT 
GOLD R Restores original field values (except 
in Layout) “eee ne es ee 
CTRL/R Refreshes the screen  -OPENLINE: 8) FLDATR 


LAYOUT PHASE ONLY 





ORDER PHASE ONLY 


GOLD» Repeats a key or operation n times GOLD C Restores conventional field 

GOLD D Creates a date field access order 

GOLD T Creates a time field TEST PHASE ONLY 

GOLD S Makes current line double size GOLD t Exits to previous field from scrolled 

GOLD W Makes current line double wide area 

CTRL/U Deletes to beginning of line GOLD J Exits to next field from scrolled area 
MLO-047-82 


Figure 3-1: Form Editor Keys 


When the instructions in this chapter tell you to press a specific key — for 
example, DELLINE — press the key labeled DELLINE. When you are 
instructed to press GOLD UNDELLINE, press the GOLD key and then the 
UNDELLINE key. 


3.3.1 Creating MENU 

MENU has only one field; in the Sample Application, the field accepts only 
a number from 1 to 5. When you create MENU, however, this field will 
accept any integer in the range 0 to 9. To restrict the integers that will be 


accepted requires programming procedures that are described later in this 
manual. 


The first step in creating MENU is to type the following: 


$ FMS/EDIT 


FMS responds by displaying the following prompt: 


File: 
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Type the name of the form you wish to create, which initially exists as a 
file: 


~File: MENU 


MENU is the name of the file containing the form. By default, FMS assigns 
a .FRM file type. 


As an alternative to the commands shown above, you can type the following 
command on one line: 


$ FMS/EDIT MENU 


FMS responds by clearing the screen and then displaying the Form Editor 
menu, shown in Figure 3-2. 


Form Editor Menu 


Phase Choice: 
| Assign form attributes 
Create or modify a form 
Assign field attributes 
Enter Named Data itens 
Modify field access order 
Test the form with the Fora Driver 
End this editor session 


Form Name: MENU 
Input. File: New form being created 





Figure 3-2: Form Editor Menu 


You use this menu to select an action to perform. You type in the name of 
the phase you wish to enter. 


First, you assign characteristics that apply to the entire form you are about 
to create. The Form phase accomplishes this. To enter the Form phase, type 
FORM; then press RETURN or ENTER. 
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Although DEPOSIT has five fields, the operator can enter data only into 
fields 3 and 5. The remaining three fields are display only. As the Sample 
Application runs, it displays data in those three fields. However, when you 
lay out the fields, you are not concerned whether fields are display only. 


Note the attributes of each field in DEPOSIT: 


1. Field 1 is a date field. When the Sample Application runs, the system 
date is automatically inserted. 


2. Field 2 has space for six digits: four to the left of the decimal point and 
two to the right. The decimal point is a field marker. Because this field 
is display only, it has no corresponding help text. 


3. Field 3 is arranged like field 2; the operator can enter only numbers in 
this field. Note that this field is fixed decimal. That is, as the operator 
fills in this field, the numbers are placed from right to left. After the 
operator types a decimal point, the remaining numbers are automati- 
cally inserted to the right of the decimal point. The help text for this 
field is “Enter amount of deposit.” If the operator fails to enter an 
amount in this field and attempts to tab to the next field, the following 
message appears at the bottom of the screen: 


Input required 
Thus, the Deposit field has the Response Required attribute. 


4. Field 4 has space for six digits. Because this field is display only, it has 
no corresponding help text. 


5. Field 5 is underlined. Any printable character can be entered in this 
memo field. The help text supplied is “Enter origin of deposit.” 


You use the Form Editor to assign these special characteristics to each field 
in DEPOSIT. The procedure for doing this is provided later in this chapter. 


After you have examined DEPOSIT, press RETURN or ENTER to get back 
to the main menu. You can either exit from the Sample Application or look 
again at MENU or DEPOSIT. 


3.3 Creating MENU and DEPOSIT 


In this section, you will create MENU and DEPOSIT. You will do the 
following for each form: 


e Assign a name 
e Lay out the background text and fields 
e Assign special attributes to each field 


e Test to verify that the visual characteristics work properly and that the 
fields accept data as intended 
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Using the Form Editor 


The Form Editor, like the Sample Application, is a program that uses forms 
for a variety of purposes. When you start the Form Editor, a menu appears 
on the screen, prompting you for a specific action to take, such as assigning 
attributes to a form you wish to create or laying out the form. This chapter 
does not explain how to use every feature of the Form Editor; rather, it tells 
how to use those features you need to create the two forms from the Sample 
Application. For complete details on assigning attributes, see the VAX-11 
FMS Utilities Reference Manual. 


As you use the Form Editor, you make extensive use of the keypad to the 
right of the terminal’s keyboard and the arrow keys above the keyboard. 
You use the keypad for the following operations: 


1. Moving the cursor. For example, you can move the cursor up or down 
any number of lines and from side to side. Using two keypad keys, you 
can also instantly move the cursor to the top left of the screen or to the 
bottom right. 


2. Deleting characters. You can delete individual characters, entire char- 
acter strings, and whole lines. 


Changing editing modes. The modes are described later. 


4. Creating special video characteristics. You can make any character or 
character string have special video qualities, such as blinking, bolding, 
or underlining. You can make characters double size or double wide, 
and you can draw lines and boxes on the screen. 


5. Inserting any amount of text into a special buffer and “pasting” it else- 
where on the screen. 


6. Centering text on a line. 


NOTE 


You should have the keypad stickup for the Form Editor, 
which is provided with the FMS distribution kit, before con- 
tinuing with this chapter. 


Figure 3-1 shows the Form Editor keys. 


Each keypad key has one or two uses. For example, the key in the top right 
is labeled DELLINE and UNDELLINE. If you press this key while laying 
out a form, the Form Editor deletes all the characters on the line the cursor 
is in. You have performed the function shown at the top of the key. 


To perform the functions shown at the bottom of the keys, you first press 
the PF1, or GOLD, key and then the key labeled with the operation. Press- 
ing GOLD and any other key having two labels executes the function 
named at the bottom of the second key. For example, if you press GOLD 
and then the DELLINE/UNDELLINE key, you restore the last line deleted 
by the DELLINE function. 
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updated as you move the cursor. Referring to this status data, you can 
always keep track of the exact line and column in which the cursor is 
located. 


Checking Aecount Menu 


Choose option (1-5): & 
| { Exit | 
2 Write a check 
3 Hake a deposit 
View the check register 


For help, press HELP. 
To continue, press keypad 1-5. 


Show account data 





As you follow the procedures in this exercise, you are instructed to make 
deliberate errors. You will then be directed to go back over your work and 
to make the necessary corrections. In this way, you get an opportunity to 
learn more about the Form Editor. 


When the cursor is at the beginning of line 2, press GOLD S to indicate that 
you want that line to have double-size characters. As you press GOLD §S, 
the cursor instantly doubles in size, and the line counter at the bottom of 
the screen indicates that you are in line 3. The double-size characters you 
are about to type will occupy lines 2 and 3. By checking the cursor size, you 
can always determine whether the line contains normal-size characters. 
Press GOLD S again; the cursor returns to its original size. Pressing GOLD 
S yet again returns you to double-size mode, as indicated by the size of the 
cursor. In double-size characters, type the title as shown here: 


Checking AcckKount Menu 


Note the deliberate misspelling of Account. Later you will go back and 
correct this error. If you make any other errors as you type, use the DE- 
LETE key to make corrections. Before proceeding, press GOLD S to change 
character size. 
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Center the Title 


Next, use the Form Editor CENTER function to center the title. To use the 
CENTER function, make sure that the cursor is located on line 3, the line 
you wish to center. Press CENTER. 


After you have centered the title, move the cursor down to the beginning of 
line 7. You can move the cursor to the beginning of line 7 in two different 
ways: 


1. Press RETURN four times. 


2. Press DOWNLINE four times; then press CHARBCK until the cursor is 
at the beginning of the line. 


When the cursor is at the beginning of line 7, press GOLD W to make this 
line have double-wide characters. As with GOLD S, you can change back 
and forth between character size each time you press GOLD W. You can 
also check the cursor size to determine which character size mode you are 
in. Type in the following text in double-wide characters: 


Choose Option (1-4): 


Now place the cursor at the beginning of line 7 and press CENTER to 
center the text you just typed. 


Next, move the cursor down to line 9, column 27, and type in the following 
text: 


1 Exit 


Type in the remaining options for MENU. Then move the cursor down to 
line 21, column 50, to type in the instructions: 


For helps press HELP, 
To continues Press Keypad 1-5, 


Draw a Box 


You now want to enclose the text in a box. Move the cursor to line 20, 
column 49. This character position is immediately to the left of and above 
the instructions. To use the DRAW function to create a box, follow the 
procedure given here: 


1. With the cursor in line 20, column 49, press SELECT. 
2. Press CHARFWD until the cursor is in column 80. 


3. Press DOWNLINE to move the cursor down three lines to line 23. Note 
that the entire area of instructions is in reverse video. The reverse 
video indicates the screen area that is in a buffer known as the select 
range — the screen area that is subject to a Form Editor function you 
choose. 
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3.3.1.1. Assigning Form Attributes: The Form Phase — You are now in the 
Form phase. The Form Attributes questionnaire appears on the screen (see 
Figure 3-3). This form contains several fields, but now you need be con- 
cerned only with the screen background field. 


Assign Form Attributes 


Form Name: MENU —‘isC 


Help Form Name: 


Screen Background: 3_ Screen Width: 1 Screen Character Set: 1 
i. As Is 1. As Is {. As Is 4. RULE 
2. Black 2. 80 Columns 2. US 5. SETS 
3. White 3. 132 Colusns 3. UK 6. SET2 


Screen Area to Clear Field Highlighting 
First Line 4. X No Highlighting 
Last Line 23 _ Blink _ Reverse 
_ Bold _ Underline 


Do you want to specify user action routines for this form? (Y/N) N 


Do you want to assign initial field attributes? (Y/N) N 





Figure 3-3: Form Attributes Questionnaire 


When the Form Editor first displays this form on the screen, note where the 
cursor is positioned. The Form Editor has already assigned the name 
MENU to this form; to keep this default form name, press TAB. 


Press TAB again to move the cursor to the field captioned Screen Back- 
ground:. If the cursor goes past this field, use the BACKSPACE key to back 
up. Type 3 to indicate that MENU is to have a white background. You are 
now finished with your work in the Form phase. 


To get back to the menu, press GOLD MENU. The Form Editor responds by 
clearing the screen and displaying the menu. You are now ready to enter 
the Layout phase. 
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3.3.1.2 Laying Out the Form: The Layout Phase — In the Layout phase, you 
type in the background text and fields that make up a form. To enter the 
Layout phase, type LAYOUT and then press RETURN. 


As you enter the Layout phase, the screen is cleared, and the Layout phase 
status line appears at the bottom of the screen. This line, shown in Figure 
3—4, provides information about the Form Editor as it is operating. Table 
3—1 describes the information given in the status line. 


Cursor {ei (i) Line Ml Column 





Figure 3—4: Layout Phase Status Line 


Table 3-1: Layout Phase Status Line Information 


Item Meaning 

Cursor 

TXT or FLD The character type at the cursor position can be either text 
(TXT) or field (FLD). 

NOR or SCR Indicates whether the line on which the cursor is positioned is 
normal (NOR) or scrolled (SCR). 

LINE (1-23) Indicates the line number. 

COLUMN (1-132) Indicates the column. 

Modes 

TXT or FLD Indicates the mode that selects whether background text 


(TXT) or fields (FLD) are entered. 


OVS or INS Indicates how characters are entered on the screen. Character 
entry mode can be either Overstrike (OVS) or Insert (INS). 


Field Name Displays the name of the current field. If you do not assign a 
field name, the Form Editor provides a default field name of 
F$nnnn. . 


Type the Background Text for MENU 


Type in the background text for MENU. Position each character in the 
exact column and line as described. 


Start with the title. Noting that the title begins on line 2, move the cursor 
to the beginning of line 2. To move the cursor down, you can press either 
DOWNLINE, found at the top right of your terminal’s keyboard, or RE- 
TURN. The line field in the status line at the bottom of the screen is 
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4. Press DRAW. 


If you make an error in the placement of the lines, you can put the lines 
back in a select range and press GOLD UNDRAW. 


NOTE 


When you create a select range, FMS works more quickly if 
you move the cursor horizontally before moving it vertically. 


When you have typed in all the background text for MENU, you are ready 
to create the field. 


Create a Field for MENU 


The one field in MENU follows the caption Choose Option (1—5):. Move the 
cursor a space beyond the colon. As the cursor enters line 7, it instantly 
changes to double-wide size. 


With the cursor in place, you are ready to create the field. Put the Form 
Editor into Field mode by pressing GOLD FIELD. The Form Editor indi- 
cates that it is in Field mode by displaying FLD | in the status line at the 
bottom of the screen in the Modes field. 


Type the following: 


9 


The character 9 is a field-validation character. This character is a symbol 
that tells the Form Driver to accept only an integer in this field during run 
time. If the operator attempts to enter a nonnumeric character in this field, 
the Form Driver will reject it, causing the terminal to beep and the screen 
to display a message. 


After you have entered the 9, return to Text mode by pressing TEXT. The 
Form Editor indicates that it is in Text mode by displaying TXT in the 
status line at the bottom of the screen in the Modes field. 

Correct MENU 


Now review your work. Go back and correct the spelling errors that you 
intentionally entered. 


1. Correct the misspelling in the title. 
2. Correct the caption for the Choose option field. 


As you correct your form, you will be experimenting with two of the Form 
Editor’s operating modes: Insert mode and Overstrike mode. These two 
operating modes refer to the way in which the Form Editor places charac- 
ters on the screen. 
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e Insert Mode 


To begin correcting MENU, press GOLD INSERT to put the Form Editor 
into Insert mode. Then press GOLD TOP to position the cursor at the top - 
left of the screen. Next, use the CHARFWD and DOWNLINE keys to 
move the cursor to the k in Acckount. Press DELCHAR. 


Checking Acckount Menu 





When you press DELCHAR, all the text to the right of the cursor moves 
over one column to the left to fill in the space vacated by the deleted k. 


e Overstrike Mode 


To correct the next error in MENU, the text that accompanies this form’s 
field, press OVERSTRIKE to put the Form Editor into Overstrike mode. 
Move the cursor to 4 in Choose option (1-4):. You can move the cursor 
either by using the arrow keys or by pressing RETURN and CHARFWD 
until the cursor is in position. When the cursor is in position, type 5. The 
new number replaces 4 in the column. The rest of the characters on line 3 
are unaffected. 


Assign Video Attributes for MENU 


You are now ready to assign video attributes to your form. Video 
attributes — blink, bold, reverse, and underline — are assigned through 
a keypad key. 

Two video attributes are in MENU: 


1. The title, Checking Account Menu, is in reverse video. 


2. The field, next to Choose Option (1—5):, is underlined. 


To make the title bold, do the following: 


1. Position the cursor in the character location immediately preceding th 
C in Checking. , 


2. Press SELECT. 


3. Move the cursor to the character position immediately following the u 
in Menu. 


4. Press VIDEO on the keypad. The Form Editor responds by displaying 
the VIDEO: prompt at the bottom of the screen. 
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5. Type BOLD in response to the prompt: 
VIDEO: BOLD 


6. Press ENTER. The Form Editor responds by bolding the title and 
repeating the VIDEO: prompt at the bottom of the screen. 


7. Type SAVE to save the video attributes just assigned: 
VIDEO: SAVE 


8. Press ENTER. 


To underline the field, do the following: 
1. Move the cursor to the 9 in the field. 
2. Press VIDEO. 


3. Type UNDERLINE in response to the prompt at the bottom of the 
screen: 


VIDEO: UNDERLINE 


4. Press ENTER. An underline appears under the 9, and the VIDEO: | 
prompt appears again at the bottom of the screen. 


5. Type SAVE to save the video attributes just assigned: 
VIDEO: SAVE 


6. Press ENTER. 


You have now completed your work in the Layout phase. The next step is to . 
assign field attributes. For MENU, the only field attributes you assign are 
Field Name and Response Required. You do this in the Assign phase. 


To exit from the Layout phase and return to the Form Editor menu, press 
GOLD MENU. Pressing GOLD MENU at any time during Layout returns 
you to the menu. 


3.3.1.3 Assigning Field Attributes: The Assign Phase — You are now ready to 
assign other attributes to the field in MENU. To enter the Assign phase, 
type ASSIGN and then press RETURN. The Form Editor responds by dis- 
playing a question below the menu (see Figure 3-5). 


Assign attributes to: g 
1. All fields 
2. New or modified fields 


3. Specific field 





Figure 3-5: First Assign Phase Question 
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Press RETURN if you want to assign attributes to a new field, the default 
choice. The screen is cleared, and MENU appears, along with a question- 
naire at the bottom, as shown in Figure 3-6. 


Checking Account Menu 


Choose Option (1-5): §& 
{ Exit 
é Write a check 


3 Make a deposit 


Assign Field Attributes 
Field Name: W000 = *————(A)_ Index Value __ 
of ___ 
_ Autotab — Right Justify _ Uppercase 
_ No Echo _ Fixed Decinal — Must Fill 
_ Display Only _ Zero Fill _ Response Required Clear Character _ 
_ Zero Suppress _ Supervisor Only —_—- UARs? ‘(Y,N) 
Default Value: 


Help Text: 





Figure 3-6: Second Assign Phase Questionnaire 


When the Form Editor displays this questionnaire on the screen, the cursor 
is positioned at @), in the Name field. In the MENU form, the field is 
highlighted in reverse video to tell you which field is being assigned attri- 
butes. MENU has only one field, but if there were more than one field, you 
would need to know which field you were working on. 


Note that F$0001 appears as the field name. This default field name is 
assigned if you do not specify a name. 


Type OPTION for the field name. Then press TAB to move the cursor 
through the list to the blank captioned Response Required. Type X. Assign- 
ing this attribute means that when MENU is displayed during run time, 
the operator must enter a value in this field. 


Move the cursor down to the field captioned Default value:. Type 2. The 
number you type in this field is the value that the Form Driver displays 
when the form first appears on the screen. That is, when the Sample Appli- 
cation displays MENU on the screen, the default value is automatically 
displayed. If the operator does not supply another number in this field, the 
Form Driver automatically performs this action. 
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Press TAB to move the cursor to the field captioned Help text:. Here you 
enter the single-line help message that the operator can see by pressing 
HELP as the Sample Application is running. The help message for this 
field is: 


Enter one of the numbers 1+ 2+ 3+ Gs or 5 


After you type in the help message, press GOLD MENU to return to the 
menu. 


3.3.1.4 Testing a Form: The Test Phase — The Test phase lets you see how 
MENU would be displayed if it were being displayed by the Sample Appli- 
cation. Type TEST and then press RETURN to enter the Test phase. Check 
the following: 


1. Make sure that the visual characteristics are as you intended. Check 
the positions of the title, the background text, and the field. 


2. Press HELP. Check to make sure that the help message appears cor- 
rectly. 


3. Enter an alphabetic character. Check to make sure that the correct 
error message appears. 


When you are satisfied that MENU is correct, press RETURN or ENTER to 
return to the menu. 


3.3.1.5 Saving a Form: The Exit Phase — After you return to the menu, type 
EXIT and then press RETURN. The Form Editor responds by displaying 
the following: 


Do vou wish to save this form? ¥ 


Press RETURN if you wish to save the form you just created. If you type N 
and then press RETURN, the Form Editor deletes the form you just cre- 
ated. 


3.3.2 Creating DEPOSIT 


You create DEPOSIT just as you created MENU. The following steps sum- 
marize the procedure: 


1. Invoke the Form Editor and type DEPOSIT as the name of the form you 
wish to create. 


2. When the menu appears on the screen, type FORM to enter the Form 
phase. In the Form phase, specify a white screen background. Return to 
the menu. 
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3. Type LAYOUT to enter the Layout phase. 
¢ In Layout, type in the background text, as planned. 
e Create the four fields. 
e Correct any errors, such as spelling, that may appear on the screen. 


e Assign video attributes to the background text and to the fields, using 
the VIDEO key. 


e Return to the menu. 

4. Type ASSIGN to enter the Assign phase. 
e Assign field names, help text, and default values for each field. 
e Return to the menu. | 

5. Type TEST to enter the Test phase. Try out your form. 


6. When you are satisfied with your form, type EXIT and indicate that 
you want to save your form. 


Review the design for DEPOSIT. Note the special video characteristics. 


MAKE A DEPOSIT 


Date: 24-SEP-82 
Current Balance $ 361.30 


Deposit $0000R00 


New Balance $ 


Heno: 
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To invoke the Form Editor, type the following: 


$ FMS/EDIT DEPOSIT 


When you press RETURN, the Form Editor clears the screen and displays 
the menu. 


3.3.2.1 Assigning Form Attributes: The Form Phase — With the menu on the 
screen, type FORM and then press RETURN. The Form Editor responds by 
displaying the Form Attributes questionnaire. Press TAB to move the cur- 
sor to the Screen Background field. Type 3 to assign a white screen back- 
ground to DEPOSIT. You are now finished with your work in the Form 
phase. 


Assign Form Attributes 


Form Name: DEPOSIT 
Help Form Names 


Screen Background: 3 Screen Width: 1 Screen Character Set: 1 
{. As Is 1. As Is 1. As Is 4. RULE 
2. Black 2. 80 Columns 2. US 5. SETL 
3. White 3. 132 Columns 3. UK 6. SET2 





Press GOLD MENU to return to the menu. 


3.3.2.2 Laying Out the Form: The Layout Phase — You are now ready to begin 
laying out DEPOSIT. Type LAYOUT to enter the Layout phase. 


Type the Background Text for DEPOSIT 


Type in the background text for DEPOSIT as shown in the SAMP form in 
Section 3.2.2. Note that the dollar sign ($) for the Current Balance, Deposit, 
and New Balance fields is background text. The dollar sign is not part of the 
field. Position the cursor in the column 49, where the Date field begins. 
Type in the following caption: 


Date: 


Create a Date Field 


When you have finished typing in the background text for DEPOSIT, you 
are ready to create the fields. The first field you create is the Date field. 
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With the cursor in column 55, press GOLD D. The Form Editor responds by 
displaying a list of date formats at the bottom of the screen: 


Date choice:_1i(month daysyvear) 2(dd-mmm-yy)3 (mm/dd/yy) 4(dd-mm-vy) 
Type 2 and then press RETURN to select the second format. 


Create Other Fields 


After you have finished creating the Date field, move the cursor to create 
the next field, Current Balance, which begins in column 42, line 5. This 
field must be able to contain up to six digits, with a decimal point (.) as a 
field marker between the first four digits and the last two. 


Since each position in this field is to contain only integers in the range 0 to 
9, type 9s, as follows: 


9999.99 


Move the cursor down to the next field, Deposit, and create that field ex- 
actly as you created the Current Balance field. Do the same for the New 
Balance field. 


The last field you create in DEPOSIT is captioned Memo:. To create this 
field, move the cursor to line 12, column 28. Since this field extends to 
column 62, it contains 35 characters. Therefore, this field should be defined 
by 35 consecutive Xs. The X is a field-definition character that tells the 
Form Driver to permit any displayable character to be entered into the 
field. You can type in each X individually, or you can use the REPEAT 
function to enter the 35 Xs more easily. 


Use the REPEAT Function 


The REPEAT function simplifies the task of typing in field-definition char- 
acters for large fields. To use the REPEAT function, do the following: 


1.. Press GOLD. 


2. Using the numeric keys on your terminal’s keyboard, type the number 
35. Note that as soon as you type 3, the following prompt appears at the 
bottom of the screen: 


Repeat: 3 


3. Type 5, then X. The field now has 35 Xs. 


Now that you have created the fields for DEPOSIT, return to Text mode by 
pressing TEXT. The Form Editor updates the Modes field in the phase 
status line. 
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Creating Video Attributes for DEPOSIT 


You are now ready to assign video characteristics to your form. Two charac- 
teristics are used in DEPOSIT: 


4. 
2, 


The title, MAKE A DEPOSIT, is in bold. 
The Memo field is underlined. 


To make the title bold, do the following: 


i, 


8. 


Move the cursor to M in MAKE by pressing either the arrow keys or 
GOLD TOP, followed by CHARFWD several times. 


Press SELECT. 
Move the cursor to the T in DEPOSIT. 


Press VIDEO. The Form Editor responds by displaying the VIDEO: 
prompt at the bottom of the screen. 


Type BOLD. 
VIDEO: BOLD 


Press ENTER. The Form Editor responds by bolding the title and 
repeating the VIDEO: prompt. 


Type SAVE to save the video attributes just assigned: 
VIDEO: SAVE 


Press ENTER. 


To underline the Memo field, do the following: 


1. 
2. 


6. 


Move the cursor to any character location in the field. 


Press VIDEO. The Form Editor responds by displaying the VIDEO: 
prompt at the bottom of the screen. 


‘Type UNDERLINE. 


VIDEO: UNDERLINE 


Press ENTER. The Form Editor responds by underlining the Memo 
field and by showing the VIDEO: prompt again. 


Type SAVE to save the video attribute just assigned: 
VIDEO: SAVE 


Press ENTER. 


You are now ready to assign attributes to the fields in DEPOSIT. 


Return to the menu by pressing GOLD MENU. The Form Editor clears the 
screen and displays the menu. 
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3.3.2.3 Assigning Field Attributes to DEPOSIT: The Assign Phase — You as- 
sign attributes to the fields in DEPOSIT while in the Assign phase. Type 
ASSIGN and then press RETURN. The Form Editor pesnuaee by displaying 
a question at the bottom of the screen (see Figure 3-5). 


Press RETURN, indicating that you want to assign attributes to the new 
fields you have created. 


The screen is. cleared, and DEPOSIT is displayed on the top half of the 
screen. (The Assign phase questionnaire (see Figure 3—7) is on the lower 
half of the screen.) 


Note that the Date field in DEPOSIT is in reverse video. This helps you 
identify the field to which you are assigning attributes. 


When you create the Date field, the Form Editor automatically assigned the 
Display Only attribute. When DEPOSIT is displayed during run time, the 
date is displayed and the operator cannot access that field. So the only 
attribute you need to assign to the Date field is the name, DATE. Press 
LINEFEED to delete the default field name. Type DATE and then press 
RETURN to assign attributes to the next field. 


Assign Field Attributes 
Field Name: Index Value ___ 
of 


_ Autotab _ Right Justify _ Uppercase 
_ No Echo X Fixed Decinal _ Must Fill 
_ Display Only ® Zero Fill _ Response Required Clear Character _ 


_ Zero Suppress _ Supervisor Only VARs? (Y,N) N 
Default Value: 


Help Text: 





Figure 3-7: Display Only Attribute 


The Form Editor again displays the Assign phase questionnaire. This time 
the reverse video highlighting is in the Current Balance field. The Form 
Editor has also supplied a default name, F$0002, for this field. 


To enter a name for the Current Balance field, first delete the default name 
by pressing LINEFEED. Then type the name CURBAL. 


Next, press TAB to move the cursor to the blank captioned Display Only. 
Type X. The cursor then moves automatically to the next blank, Right 
Justify. Type X. In the fields captioned Zero Fill and Zero Suppress, type X. 
The Zero Fill attribute causes the Form Driver to pad with zeros all values 
returned to the application program. The Zero Suppress attribute causes 
the Form Driver to provide blanks in place of leading zeros when the cur- 
rent balance figure is displayed during run time. 
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Finally, type 0 in the blank captioned Clear Character. The 0 causes the 
Form Driver to put 0s in each unused data position in the field. When you 
assign the Zero Suppress attribute, FMS requires you to also use the Zero 
Fill attribute and to specify a Clear Character. After you have assigned 
these attributes, press RETURN to move to the next field, Deposit. 


After typing the name DEPOSIT, press TAB until the cursor is positioned 
next to the blank captioned Fixed Decimal. Type X. 


Next, put an X by the Zero Fill and Response Required attributes. 
Move the cursor to the blank captioned Clear Character. Type 0. 


Since the Deposit field will be filled in by the operator, you should provide a 
help text line. To do this, press TAB to move the cursor to the Help Text 
field. Type the following line: 


Enter amount of deposit 


Press RETURN to assign attributes to the next field, New Balance. Assign 
the following attributes to this field: the name NEWBAL and the Display 
Only and Right Justify attributes. 


Finally, you assign attributes to the Memo field. Assign the name MEMO 
and the Response Required attribute. You must also type the following help 
text line: | 


Enter the origin of deposit 


You have now finished assigning field attributes to the Deposit field. Press 
GOLD MENU to return to the menu. 


3.3.2.4 Alternative Method of Assigning Field Attributes — You have been 
assigning field attributes to forms from the Assign phase. The Form Editor 
offers an alternative to this means of assigning field attributes. After you 
have created a field and the cursor is still in that field, press GOLD 
FLDATR. The Form Editor responds by displaying the Assign phase ques- 
tionnaire on the lower half of the screen. You can immediately assign field 
attributes. When you complete that questionnaire, you are still in the Lay- 
out phase and can continue laying out the form. 


You can try this method by returning to the Layout phase for either form 
you created. Move the cursor to any field on the screen and press GOLD 
FLDATR. You return to the Form Editor menu by pressing GOLD MENU. 


3.3.2.5 Testing a Form: The Test Phase — Type TEST and then press RE- 
TURN to enter the Test phase. The Form Editor displays DEPOSIT as if it 
were being displayed by the Sample Application. As you test this form, 
check the following: 


1. Make sure that the visual characteristics are as you intended. Check 
the position of the title, the background text, and the fields. 
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2. Press HELP. Check to make sure that the help message appears cor- 
rectly for each field. 


3. Enter invalid data into the fields. Check to make sure that the correct 
error messages appear. 


When you are satisfied that DEPOSIT is correct, press RETURN or ENTER 
to return to the menu. 


If you discover that you need to modify DEPOSIT, reenter any phase —_ 
Form, Layout, or Assign — and make the corrections. You will then want 
to enter the Test phase again. 


3.3.2.6 Saving a Form: The Exit Phase — After you return to the menu, type 
EXIT and then press RETURN. The Form Editor responds by displaying 
the following question: 


ba | Vv 


Do you wish to save this form? ¥ 


Press RETURN if you wish to save the form you just created. If you type N 
and then press RETURN, the Form Editor deletes the form you just cre- 
ated. 


3.4 Creating a Help Form 


This section describes how to create a help form. When you ran the Sample 
Application, you saw the help form associated with the menu (see Figure 
3-8). 


You will create the help form for MENU and will connect it with MENU. 


To create a help form, you follow the same steps as you did to create MENU 
and DEPOSIT. The only difference between those forms and a help form is 
that a help form cannot contain any fields, except for time and date fields. 
Help forms only display text. The Form Driver ignores any other fields that 
may be in the help form. 


The first step is to invoke the Form Editor and to create the form entitled 
HMENU. 


3.4.1 Creating HELP_MENU 


Type the following command to invoke the Form Editor and to specify 
HMENU as the form you wish to create: 


$ FMS/EDIT HMENU 


FMS responds by clearing the screen and then displaying the Form Editor 
menu. Select the Form phase. 
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Help for SAMP Menu 


 SAMP simulates some functions of electronic banking. In this application 
you can make deposits and write checks at your terminal. 


Your account at this bank has already been set up. You have nade several 
deposits and have written some checks. When SAMP starts, you are able to 
request the following functions by typing the number and then pressing 
RETURN. You can stop SAMP by typing 1 or by pressing keypad period. 


t To leave SAMP and return to operating system level. 


Sree eeraeene You can see the data associated with your account. 


For more help, press HELP. 
To continue, press RETURN. 





Figure 3-8: Menu Help Form 


When in the Form phase, assign the name HELP_MENU to this help form. . 
Give this form a white screen background. 


Return to the Form Editor menu and select the Layout phase. 


When in Layout, type in the text as shown in Figure 3-8. Assign the appro- 
priate video attributes. 


When you have finished the Layout phase, return to the menu and exit. 
You do not need to use the Assign phase unless your help form has a time 
or a date field. If you were to create fields in a help form, the Form Driver 
would ignore them during run time. 


The next step to take in creating the help form is to associate it with the 
menu form. To do this, you need to edit MENU with the Form Editor again. 


3.4.2 Associating HELP_MENU with MENU 
Invoke the Form Editor and specify MENU as the form you wish to modify. 


$ FMS/EDIT. MENU 


FMS responds by clearing the screen and then displaying the Form Editor 
menu. Select the Form phase. 
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When in the Form phase, move the cursor to the field captioned Help Form 
Name. Type the name of the help form you just created, HELP_MENU. 


Assign Form Attributes 


Form Name: 


MENU 
Help Form Name: HELP_MENIM 





HELP_MENU is now associated with MENU. Press GOLD MENU to re- 


turn to the menu and to exit, saving the form. 
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Chapter 4 
Creating a Form Library 


As you read this chapter, you will: 

e Create a library file 

e Store MENU, DEPOSIT, and HMENU in the library 
e Get a directory listing of the library 


e Examine a form description of MENU 


Figure 4—1 shows the steps in the FMS application development cycle. The 
shaded portions are covered in this chapter. 


4.1 Create a Library File 


To create a library for the forms you just created, invoke the Form Librar- 
ian and specify SUBSET.FLB as the form library file you wish to create: 


$ FMS/LIBRARY/CREATE SUBSET.FLB 


FMS responds by printing the —Files: prompt. Enter the following com- 
mand: | 


~Files: MENU »DEPOSIT »HMENU 


Create forms 
(Form Editor) 


Binary forms 


Create COBOL 
data definition 


COBOL data 
definition 





MLO-048-82 


Figure 4-1: FMS Application Development Cycle 
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4.2 Obtain a Library Directory Listing 


Once you have stored the three forms in SUBSET.FLB, get a directory 
listing of that library file by specifying /DIRECTORY in the FMS command 
line. Use the following command line to obtain a directory listing of 
SUBSET.FLB. 


$ FMS/DIRECTORY SUBSET 


FMS then displays the following directory listing: 


Form Librarian V2.0 
21-SEP-1982 10:06 


Library USER: CSMITHISUBSET.FLBil» created: 21-SEP-1982 10:06 
Date and time of last modification: 21-SEP-1982 10:06 


MENU 
DEPOSIT 
HEL P.MENU 


4.3 Interpret a Form Description 
To obtain a form description of MENU.FRM, type the following command: 


$ FMS/DESCRIPTION SUBSET/FORM_NAME=MENU/OUTPUT=MENU 


The command above produces the form description MENU.FLG, shown in 
this section. For easier reference, we will discuss the form description in 
sections. Form descriptions are useful as hard-copy references of forms. For 
more information on form descriptions, see the VAX—11 FMS Utilities Ref- 
erence Manual. 


A form description is a set of Form Language statements that describe a 
form. The following section of MENU.FLG consists of statements that de- 
scribe the form attributes of MENU. 


| FMS Form Description ArprPlication Aid 
| Version 2.0 


FORM NAME=’MENU ’ 
HELP_FORM= ’HMENU ‘ 
AREA. TO_CLEAR=1:23 
WIDTH=80 
BACKGROUND=WHITE 
DBLWID=7 
DBLSI2Z=2 
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The next section of MENU.FLG consists of statements that describe the 
background text in MENU — the location and video attributes of each bit 
of background text. 


TEXT (2+9) ‘Checking Account Menu’ 
BOLD 


5 
TEXT (791) ¢ Choose option (1-5): ° 
5 


TEXT (9927) ‘1 Exit’ 
5 
TEXT (11527) ‘2 Write a check’ 


5 
TEXT (13°27) °3 Make a deposit’ 
5 
TEXT (158,27) ‘4 View the check register’ 


q 
TEXT (17+27) ‘3S Show account data’ 


4 
TEXT (20:49) ’Llaeq9saqqqqqqgqgqqqggqqqqagqqqgqqqqqqqqqk ” 
CHARACTER.SET=RULE 


+) 
TEXT (21+49) ‘x’ 
CHARACTER SET=RULE 


5 
TEXT (21;50) ‘For help, press HELP, ’ 


3 
TEXT (21580) ‘x’ 
CHARACTER SET=RULE 


5 
TEXT (22/49) ‘x’ 
CHARACTER_SET=RULE 


5 
TEXT (22;+50) ‘To continues Press Keypad 1-5,’ 


3 
TEXT (22+80) ‘x’ 
CHARACTER_SET=RULE 


3 
TEXT (23,49) ‘massqqgqqggqgqqgqgqgqqgqqgqgqgqgqqqqqqqdq ) ’ 
CHARACTER_SET=RULE 


The last section of the form description describes the field in MENU — the 
position of the field on the screen and the field attributes. 


ATTRIBUTE_DEFAULTS FIELD 
CLEAR_CHARACTER=’ ‘ 
NOAUTOTAB BLANK FILL NOBLINKING NOBOLD NOREVERSE 
NOUNDERLINE NODISPLAY ONLY ECHO NOFIXED_DECIMAL 
LEFT.JUSTIFIED NOSUPERVISOR_ONLY NOSUPPRESS NOUPPERCASE 


3 


FIELD NAME=‘OPTION’ (721) 
PICTURE='9° 
HELP=’Enter one of the numbers 1L+ 25 B+ G+ or 3’ 
DEFAULT=/’2’ 
RESPONSE_REQUIRED UNDERLINE 


END_OF.FORM NAME=‘MENU’ 35 
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4.4 Obtain a Form Image 


The last section of this chapter tells how to obtain a form image and how to 
interpret it. 


To obtain an image of the form MENU, enter the following command: 


$ FMS/DESCRIPTION/IMAGE SUBSET/FORM_NAME=MENU/OUTPUT=MENU 


FMS produces the file MENU.LIS shown below. 


Form. MENU 


1 2 3 4 ke) 6 7 
123456789012345678901234586789012345678901234567890123456789012345678901234567899 


11 Li 

2! {2 

3] CHECKING ACCOUNT MENU 13 

4) 14 

5] 1S 

Gl 16 

7i Choose oFtion (1-530 2 17 

81 i8 

91 1 Exit rs 

101 110 
iii 2 Write a check tii 
121 fi2 
i3! 3 Make a derposit 113 
14} 114 
ist 4 View the check resister Lis 
1Gi 1iG 
171 3 Show account data 117 
igi 118 
ig! 119 
20] Hen ee we ee nn ee eee +420 
21] [For help, press HELP (PF2). 1121 
22! iTo continue, type a number (1-3) and press RETURN.! 122 
231 SSS SSeS Sa a Se ea nee ar ee Pe Se ee eee +123 


1234567890123456789012345678901234567890 1234567890 12345678901 2345678901234567890 
1 2 3 4 3 6 7 8 


This image shows how MENU appears on the screen. The title, CHECK- 
ING ACCOUNT MENU, and the line Choose Option are not shown in 
double-size and double-wide characters, because of the limitations of a line- 
printer. The image shows the location of background text and fields that 
are in normal-size characters. When working with hard-copy listings of 
forms, it is useful to attach copies of the form image to the form descrip- 


tions. 
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Chapter 5 
Writing an Application 


As you read this chapter, you will: 
e Learn about some basic Form Driver concepts 


e Write a subset of the Sample Application, using the three forms you cre- 
ated in Chapter 3 


e Learn about some basic Form Driver calls and incorporate them in the 
subset application 


5.1 Form Driver Concepts 


The Form Driver consists of subroutines that provide services to make it 
easy for an application to display forms and to transfer data between the 
terminal and the Form Driver. The Form Driver services are invoked by 
Form Driver calls in the application. The Form Driver routines accomplish 
the following tasks: 


e Establish communication links among the Form Driver, the application, 
the terminal, and the form library 


e Display the forms on the screen 

e Accept operator input into the fields of the form 
e Determine whether the operator input is valid 
e Send the operator input back to the application 
e Move the cursor from one field to another 


e Display messages and help for the operator 
You implement Form Driver services by including Form Driver calls in the 


source program. You then compile and link the application program with 
the Form Driver routines. During run time, the Form Driver routines are 
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invoked in much the same way as routines available from any object pro- 
gram library. 


As shown in Figure 5-1, the Form Driver is a part of the application pro- 
gram. Form Driver calls set up all the I/O channels and work areas that 
you specify. 






Application 
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Figure 5-1: Role of the Form Driver in an Application Program 


In this section, you will learn about the categories of Form Driver calls. In 
the programming exercises in this chapter, you will use the calls that are 
demonstrated in the Sample Application. Finally, you will learn how the 
Form Driver performs string handling. Understanding string handling is 
important when adapting your programming language to FMS. 


5.1.1 Form Driver Calls 


Form Driver calls are implemented in the application program in much the 
same way as any other subroutine calls. The format of the calls depends on 
the program language used. This section briefly describes the kinds of calls 
and lists the calls used in the subset application. 


5.1.1.1. Functional Division of Calls — Because the Form Driver provides a 
number of services, the calls can be divided into the following categories: 


e Control calls 
e Field-level calls 
e Form-level calls 


¢ Utility calls 


The services that the calls provide are listed under each category. 
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Control Calls 

e Establish communication lines with the terminal and the form library 
e Establish work areas for forms and the terminal 

e Manipulate files and work areas 


e Detach communication paths previously established 


Field-Level Calls 


e Request operator input to a field 
e Alter characteristics of a field 

e Send data to a field 

e Return a description of a field 


e Return a field’s context, name, and other data 


Form-Level Calls 

e Clear the terminal screen 

e Display a form 

e Return all field values in one step 


e Send values to all fields in one step 


Utility Calls 

e Cancel a call 

e Send a message to the terminal 
e Return a line from the terminal 
e Return Named Data from a form 


e Return status after the last call executed 


5.1.1.2 Form Driver Calls Used in the Subset Application — In this chapter, 
you will practice using Form Driver calls. After completing this chapter, 
you can turn to the Form Driver Reference Manual to write your own FMS 
applications. 


In the call descriptions in this chapter, some arguments for some of the 
calls have been omitted for the sake of simplicity. The Form Driver Refer- 
ence Manual provides complete descriptions of each call. 
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The following calls are used in the exercises: 


FDV$ATERM Attach terminal 
FDV$AWKSP ~~ Attach form workspace 
FDV$CDISP Clear screen and display form 
FDV$DTERM Detach terminal 

FDV$GET Get value for specified field 
FDV$LCLOS Close form library 
FDV$LOPEN Open form library 


FDV$PUT Output value to specified field 
FDV$PUTL Output line to screen 
FDV$STAT Return status from the last call 


FDV$WAIT Wait for operator 


5.1.2 String Handling 


This section describes how the Form Driver manipulates data that it gets 
from the operator. Your application accesses data from forms in a variety of 
ways and can do the following: 


e Use the Form Driver FDV$GET call to request operator input to a spe- 
cific field and return that data in a variable to the application and the 
Form Driver workspace. 


e Use the Form Driver FDV$GETAL call to request input from all the 
fields in which the operator can provide input — readable fields — on 
the form and put that data in the Form Driver workspace. Your applica- 
tion can then access the workspace to return individual field values. 


e Get operator input to all readable fields in a form and store the contents 
of all fields, both readable and nonreadable, as a single string in the 
application’s data base. This is done with the FDV$GETAL call, specify- 
ing the variables to which all field values are to be returned. 


This chapter shows how to implement some of the Form Driver’s string- 
handling capabilities that appear in the Sample Application. How an appli- 
cation handles strings depends on the language used, however. For specifics 
on how to handle strings in a given language, see the VAX-—11 FMS Lan- 
guage Interface Manual. 


5.2 Sample Application Subset 


This section describes the main program and subroutines of the subset 
application that you will code in this chapter. The subset is made up of the 
following program sections: 


e A main program 
e A subroutine that displays and services the MENU form 
e A subroutine that executes the DEPOSIT form 
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You will also insert dummy subroutines, called stubs, whose primary pur- 
pose is to appear where they do in the Sample Application but without any 
particular function. You will provide stubs where the subset application 
performs the following tasks: 


e Initialize account data 

e Process the check-writing form 
e Process the deposit form 

e Show the account data 


e Show the check register 


Instead of performing the tasks shown above, the stubs, when called during 
run time, will display a message on the screen, indicating that their func- 
tion is not implemented yet. Providing these stubs in the subset application 
enables you to run the subset and to test all the options available in the 
menu. 


NOTE 


To make efficient use of VAX-—11 BASIC, each subroutine in 
the subset application is invoked as a function, as in the 
Sample Application. 


The subset application does not use the keypad. Therefore, when you run 
the subset application, you will need to indicate menu choices by using the 
numeric keyboard. 


5.2.1 The Main Program 

The main program of the subset application does the following: 
1. Sets up a general work area for the program. 

2. Sets up a terminal control area for the Form Driver. 

3. Attaches the terminal to the Form Driver. 

4. Attaches the workspace to the terminal. 
5 


Establishes a communication line between the form library and the 
Form Driver. 


6. Calls a subroutine, INACCT, that reads account data from a data file. 
Since this subroutine will not be coded in this chapter, it will return to 
the main program only arbitrary account figures. 


7. Calls a subroutine, MENU, that processes all menu requests. 
8. Performs a general cleanup. 


9. Exits. 
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5.2.2 Subset Subroutines 


Following are descriptions of the subroutines that you will include in the 
subset from the Sample Application. 


INACCT Returns account data to the main program. In this subset, 
INACCT returns only the summary figures for the checking account: start- 
ing balance, total checks written, total deposits made, and current balance. 


MENU Accepts operator input from the menu form and branches control 
to the appropriate subroutine to service the action requested. Control al- 
ways returns to this subroutine until the operator exits. Then this subrou- 
tine returns control to the main program. This subroutine uses the form 
MENU that you created in Chapter 3. 


WRITCH Performs the check-writing procedure in the Sample Applica- 
tion. In the subset, this subroutine is a stub and displays a message indicat- 
ing that the subroutine is not implemented. The WRITCH subroutine then 
returns control to the MENU subroutine. 


MAKDEP Instructs the operator to enter a deposit and a memo of the 
deposit. This is the second subroutine for which you created a form in 
Chapter 3. This subroutine makes use of the keypad; if the operator presses 
keypad period, the Form Driver displays the MENU form and returns con- 
trol to subroutine MENU. 


VUEREG Permits the operator to view the check register for the check- 
ing account. In the subset, this subroutine displays a message and returns 
control to subroutine MENU. 


VUEACT Permits the operator to view the account data. This subroutine 
is not implemented in this subset. Therefore, when the operator chooses 
this option, VUEACT displays a message that this subroutine is not imple- 
mented. 


GETSTA Checks the status of the Form Driver after the last call exe- 
cuted. This subroutine displays an error message if the results of the last 
Form Driver call executed produced an error. The final statement of the 
application is at the end of this subroutine. 


5.2.3 Preparing the Main Program 


Before you continue with this section, create a file in which you can enter 
the statements given in this chapter. Use the name SUBSET.BAS for this 
file. As you are instructed to enter statements, enter them as shown in 
SUBSET.BAS. : 


5.2.3.1 Initializing Calls — The first instructions in the subset’s main pro- 
gram are the initializing calls. These calls set up the Form Driver, the form 
library, the workspace, the terminal control area, and the appropriate com- 
munication links among those components. 
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You use the initial Form Driver calls to do the following: 


e Attach the terminal to the Form Driver 
e Attach a workspace for the Form Driver 


¢ Open the form library containing the forms the application will use 


In this section, you will write the statements that use these calls and see 
how the calls work. Descriptions of the calls used in the subset are in- 
dented. The statements you enter into the source file for SUBSET.BAS 
appear in red type. Note that the complete subset program appears in the 
Appendix. | 


Attaching the Terminal — FDV$ATERM 


Before an FMS application and a terminal can communicate, the ter- 
minal must be identified. A terminal control area, an area in memory 
used by the Form Driver, must also be established for that terminal. 


The FDV$ATERM call identifies the terminal and establishes a termi- 
nal control area (see Figure 5-2). The FDV$ATERM call has the fol- 
lowing format: 


FDV$ATERM ( tea, size, channel ) 


The argument tca represents an area in memory set aside by the ap- 
plication program for the terminal control area, size represents the 
size, in bytes, of the TCA, and channel represents the I/O channel. 














Application 
CALL 
FDV$ATERM 









Form Driver 
ATERM 
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Figure 5-2: Attaching a Terminal 


Enter the following statements into SUBSET.BAS to set up a general work 
area and a terminal workspace and to attach the terminal: 


130 DIM WORKSPACE? ¢(¢ 3 ) ! General workspace 
140 DIM TCAZ ( 3} 1 Terminal control area 
1040 CALL FDV#ATERM ( TCA ()5 12%, 2% ) 


The value 3 in the DIM statements for WORKSPACE% and TCA% repre- 
sents a 12-byte area in memory. VAX-—11 BASIC interprets the value 3 to 
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represent three 4-byte words, or 12 bytes. In the FDV$ATERM call, the 
argument 12% represents the size, in bytes, of the TCA, and 2% represents 
the I/O channel number. 


Attaching the Workspace — FDV$AWKSP 


To display a form on a terminal screen, your program must put a form 
description in a workspace and call the form from that workspace. 


The Form Driver call that attaches a workspace to a terminal is 
FDV$AWKSP (see Figure 5-3). The FDV$AWKSP call has the follow- 
ing format: 


FDV$AWKSP ( wksp, size ) 


The argument wksp represents the area in memory set aside for the 
workspace, and size represents the size, in bytes, of the workspace. 














Application 
CALL 
FDVS$AWKSP 






Form Driver 
AWKSP 
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Figure 5-3: Attaching a Workspace 


Enter the following statement to attach a workspace size of 2000 bytes to 
the terminal: 


1042 CALL FDV$AWKSP ( WORKSPACEZ ()+ 2000% ) \ C=FN.GETSTA 


The accuracy of the initial estimate of the workspace size is not critical, but 
applications run slightly faster when the size is larger than the workspace 
requirements of the largest form in the application. To determine the size, 
in bytes, of each form in a library, use the FMS/LIBRARY/FULL command. 


In the statement above, C=FN.GETSTA calls the FMS status-checking 
function, which is described later. It is good programming practice to check 
the FMS status after Form Driver calls that can affect subsequent 
processing — attaching, opening, or displaying operations. 
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Opening a Library Channel — FDV$LOPEN 


Forms are used to transfer data between the application program and 
the terminal screen. Forms may be memory resident — linked with 
the application program — or stored in a form library. To retrieve a 
form stored in a library, the library must be opened, and an I/O chan- 
nel connecting the library and the Form Driver must be established. 


The FDV$LOPEN call establishes an I/O channel between the Form 
Driver and the form library (see Figure 5-4). The FDV$LOPEN call 
has the following format: 


FDV$LOPEN ( filspc, channel ) 


The argument filspe represents the name of the library file that you 
wish to open, and channel represents the [/O channel that connects 
the library file to the Form Driver. 













Application 
CALL 
FDV$LOPEN 







Form Driver | 
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Figure 5—4: Opening a Library Channel 


Enter the following statement to open the library SUBSET.FLB and to 
specify an I/O channel to be used between the library and the Form Driver: 


1050 CALL FDY$LOPEN ( ‘SUBSET’, 1% ) \ C=FN.GETSTA 


The GETSTA function call appears again at the end of the statement. 


5.2.3.2 Coding the Body of the Main Module — You will now enter the state- 
ments for coding the body of the subset main module. In the subset, the 
body consists of two statements: a call to the subroutine INACCT and a call 
to the subroutine MENU. INACCT initializes the account information. In 
this subset, INACCT establishes a current balance for the checking account 
and returns control to the main module. MENU processes all menu re- 
quests. 
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Enter the following statements: 


1115 C = FN.INACCT ! Initialize account information 
1170 C = FN.MENU 1 Process all menu requests 


When the operator exits from the menu, control returns to the main pro- 
gram, and the closeout procedure statements are processed. © 


5.2.3.3 Closing Calls — At the end of the main module, several statements 
execute the closing procedure for the FMS components. These statements 
close the I/O links opened in the main module, detach the terminal and 
workspace(s), and perform a general cleanup. 


The closing procedure calls are as follows: 


FDV$LCLOS Close form library 
FDV$DWKSP Detach form workspace 
FDV$DTERM Detach terminal 


Closing the Form Library — FDV$LCLOS 


The FDV$LCLOS call closes the I/O channel established between the 
library file and the Form Driver. FDV$LCLOS has the following 
format: 


FDV$LCLOS 


This call has no arguments. 


Detaching the Form Workspace — FDV$DWKSP 


The FDV$DWKSP call detaches the workspace from the application 
program. FDV$DWKSP has the following format: 


FDV$DWKSP ( wksp ) 


The argument wksp represents the area of memory set aside for the 
Form Driver workspace. 


Detaching the Terminal — FD V$DTERM 


The FDV$DTERM call detaches the operator’s terminal from the ap- 
plication program. This call also cleans up the terminal and makes it 
usable for other programs. FDV$DTERM has the following format: 


FDV$DTERM ( tca ) 


The argument tca represents the area of memory set aside for the 
terminal control area. 
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Enter the following statements to execute the FMS closing procedure: 


1200 CALL FDY$LCLOS 

1208 CALL FDVS$DWKSP ( WORKSPACEZ () ) 
i215 CALL FDVSDTERM ( TCAZ () ) 

1220 6©«GOTO 15999 


The last line, GOTO 15999, transfers control to the end statement of the 
subset. 


5.2.4 Coding the INACCT Subroutine 


The INACCT subroutine returns to the main program the following arbi- 
trary figures: 


SBALANCE% The starting balance: $503.75 
TOTPAY% The total amount written in checks: $213.45 
TOTDEP% The total amount of deposits made: $1123.23 
BALANCE% The current balance: $1413.53 


Each variable is initially assigned a numeric value. Later in this chapter, 
you will see how these numbers are converted into strings that are output 
to the appropriate forms in the subset application. The INACCT subroutine 
has no Form Driver calls. 


Enter the following statements, which make up the body of the INACCT 
subroutine. 


4000 DEF FN. INACCT 
4005 SBALANCE% = 530375 
4010 TOTPAY’ = 21345 
4015 TOTDEP* = 112323 
4020 BALANCEZ = 141353 
4080 FNEND 


5.2.5 Coding the MENU Subroutine 
The MENU subroutine does the following: 


1. Accepts input from the menu form and branches control to the appropri- 
ate routine 


2. Continues accepting input until the operator enters 1 (Exit) 


Before entering the code for this subroutine, become familiar with the Form 
Driver calls used in this subroutine. 
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Clearing the Screen and Displaying a Form — FDV$CDISP 


The FDV$CDISP call clears the terminal screen and displays a speci- 
fied form. In the MENU subroutine, FDV$CDISP displays the menu 
form that you created in Chapter 3. 


When processing the FDV$CDISP call, the Form Driver retrieves the 
specified form from the library, places.a description of that form in the 
workspace, clears the terminal screen, and displays the form on the 
terminal screen (see Figure 5-5). 











Application 
CALL 
FDV$CDISP 










Form Driver 
CDISP 
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Library 





Figure 5-5: Displaying a Form 
The FDV$CDISP call has the following format: 
FDV$CDISP ( frmnam ) 


The argument frmnam represents the name of the form that the Form 
Driver is to display on the screen. 


In the subset, the corresponding statement for this call is as follows: 
CALL FDV$CDISP ( ‘MENU’ ) 


You will be instructed later to enter this statement. 
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Requesting Operator Input to a Field — FDV$GET 


The FDV$GET call requests the operator’s input to a specified field. In 
the MENU subroutine, the GET call is used to request the operator’s 
choice of checking account procedure to enter. 


When processing the FDV$GET call, the Form Driver reads the opera- 
tor’s input to a specified field, copies that input to a variable name 
specified in the GET call statement, and sends that variable to the 
application (see Figure 5-6). 


MAIN MEMORY 










Application 
CALL FDV$GET 


Form Driver 
GET 
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Figure 5-6: Requesting Operator Input to a Field 


The Form Driver uses the following procedure when executing the 
FDV$GET call: 


1. The application issues the FDV$GET call for a value. 

2. The Form Driver requests the value from the operator. 
3. The Form Driver retrieves the value. 
4 


The Form Driver copies the value into the workspace and into the 
application program. | 
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The FDV$GET call has the following format: 
FDV$GET ( fldval, fldtrm, fldnam ) 


The argument fldval represents the variable into which the input to 
the specific field is copied, fldtrm represents the code for the field 
terminator key struck, and fldnam represents the name of the field 
from which the input is being retrieved. 


The subset application call that requests operator input to the menu 
has the following format: | 


CALL FDV$GET ( OPTIONS, TERMINATOR“, ‘OPTION’ ) 


Displaying a Line on the Terminal Screen — FDV$PUTL 


The FDV$PUTL call displays a message on a specified line on the 
terminal screen. In the MENU subroutine, the FDV$PUTL call is used 


to display a message indicating invalid input by the operator into the 
OPTION field. 


The FDV$PUTL call has the following format: 
FDV$PUTL ( text [,line] ) 


The argument text represents the character string to be displayed on 
the screen, and line represents the number of the line on which the 
character string is to be displayed. If line is not supplied, the Form 
Driver displays the character string on the bottom line of the screen. 


If the operator attempts to enter an invalid number, the message “IN- 
VALID CHOICE” is displayed by the following call: 


CALL FDV$PUTL (‘INVALID CHOICE?’ ) 


Coding the Body of the MENU Subroutine 


The 


MENU subroutine uses a loop to continue displaying the menu after 


processing an operator choice. A computed GOTO dispatches to the subrou- 


tine 


which processes the operator’s request. 


Enter the following statements, which make up the body of the MENU 


subroutine. 

5000 DEF FN.MENU 

S005 | Menu choices: 

S010 1 1 = Exit 

S015 | 2 => Write checks 

S020 ! 3 => Make a deposit 
S023 i 4 => Yiew register 
Sago | § => Yiew account data 


As required in VAX—11 BASIC, the following statement pre-extends the 
variable OPTION$, which is to contain the operator menu choice: 


8504 


O OPTIONS = ’ % 
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The 


following statements make up a computed GOTO loop to dispatch to 


the appropriate subroutine. Calls to the status check function appear after 
the FDV$CDISP and FDV$GET calls. 


5045 
Sos0 
5070 
5075 


The 


WHILE 1 = 1 
CALL FDOV$CDISP ( ‘MENU’ ) \ C=FN,.GETSTA 
CALL FDY$GET ( OPTIONS:+s TERMINATOR%»s ‘OPTION’ ) \ C=FN.GETSTA 
ON VAL ( OPTIONS ) GOTO SO82,s 30905 Sidd, 5110, S120 


remaining statements of MENU branch control to the subroutine(s) 


processing the operator’s menu request. After a subroutine has been exe- 
cuted, control resumes at statement 5130, which branches back to the be- 
ginning of the computed GOTO loop. 


50681 
S082 
5085 
S0g0 
5095 
S100 
5105 
o110 
5115 
$120 
5136 
5140 


! Option i: Exit 
FNEXIT 
! Option 2: Write checks 
C=FN.WRITCH \ GOTO 5130 
! Orption 3: Make a deposit 
C=FN.MAKDEP \ GOTO 31306 
! Option 4: View register 
C=FN.YUEREG \ GOTO 3130 


! Option S: View account data 
C=FN.YUEACT \ GOTO 3130 
NEXT 
FNEND 


5.2.6 Coding the WRITCH Subroutine 
The WRITCH subroutine does the following: 


1. Displays the following message on the bottom of the screen: 


Write acheck - not implemented yet 


2. Waits for the operator to press ENTER or RETURN 


3. Returns to the main menu 


WRITCH uses two Form Driver calls: FDV$PUTL and FDV$WAIT. Here 
we will discuss only the FDV$WAIT call. 


Waiting for Operator Input — FDV$WAIT 


The FDV$WAIT call causes the Form Driver to wait until the operator 
signals to proceed. This call is particularly useful for pausing until the 
operator reads a message. The FDV$WAIT call has the following 
format: 


FDV$WAIT ( [fldtrm] ) 


The argument fldtrm is the variable to which the Form Driver returns 
the terminator code of the key struck to end the wait condition. If you 
do not supply an argument with the WAIT call, the Form Driver will 
not return the terminator the operator entered. 
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Coding the Body of WRITCH 


The WRITCH subroutine uses the FDV$PUTL call to display the following 
message on the bottom of the screen: 


Write a check - not implemented yet 


Enter the following statements to make up the WRITCH subroutine: 


11000 DEF FN.WRITCH 

11005 CALL FDOV#PUTL ( ‘Write a check - not implemented yet’ ) 
11010 CALL FDVSWAIT 

11015 FNEND 


5.2.7 Coding the MAKDEP Subroutine 
The MAKDEP subroutine does the following: 
1. Displays the DEPOSIT form, which you created in Chapter 3 


2. Writes the checking account’s current balance in the Current Balance 
field 


Requests the operator’s input for the deposit and the deposit memo 


4. Adds the deposit to the current balance and updates the Current Bal- 
ance field 


5. Displays, once the deposit has been entered, the following message on 
the bottom of the screen: 


Deposit made» press RETURN or ENTER to continue 
The MAKDEP subroutine uses the following Form Driver calls, which we 
have already presented: 
FDV$CDISP Clears the screen and displays the DEPOSIT form 


FDV$GET Gets the operator’s input for the Enter Deposit and Memo 
fields 


FDV$PUTL Displays a message on the bottom line of the screen, say- 
ing that the deposit has been made 


FDV$WAIT Waits for the operator to signal for the Form Driver to 
continue after the deposit message has been displayed 


The MAKDEP subroutine also uses the FDV$PUT call to display the cur- 
rent balance, determined previously by the INACCT subroutine or by pre- 
vious calls to MAKDEP, in the Current Balance field. 


Output Value to a Specified Field — FDV$PUT 


The FDV$PUT call displays a value in a specified field. In the 
MAKDEP subroutine, the FDV$PUT call is used to display the date 
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and the current balance in the Date and Current Balance fields, respec- 
tively. 


The FDV$PUT call has the following format: 
CALL FDV$PUT ( fidval, fldnam [,fldidx] ) 


The argument fldval represents the variable to be displayed, fldnam 
represents the field in which the variable is to be displayed, and fldidx 
represents the index value of the field represented by fldnam. (The 
argument fldidx is used only if the field is indexed, described in Chap- 
ter 7.) 


The statement that displays the current balance in the subset applica- 
tion follows: 


CALL FDVSPUT ( STRS( BALANCE% )+ ‘CURBAL’ )} 


(Note that the BASIC STR$ function is used in this statement, de- 
scribed later.) 


BASIC Functions in the MAKDEP Subroutine 


The BASIC functions STR$, SPACE$, and VAL are described here for those 
who are not familiar with VAX—11 BASIC. These functions are used in 
MAKDEP to perform the following operations: 


STR$ Converts a numeric value to a string value. For example, the 
current balance, represented by the variable CURBAL, ini- 
tially has the numeric value 50375. The STR$ function converts 
the number 50375 to the string 50375’. The Form Driver deals 
only with character strings, not with numbers, for values of 
fields. 


SPACE$ Creates a string of space characters, as many as specified. 


VAL Extracts the numeric value from a string. For example, the 
VAL function can extract the value 50375 from the string 
‘50375’ for subsequent arithmetic operations. This function does 
the reverse of the STR$ function. 


Coding the Body of MAKDEP 


Statements 12000 to 12065 display the form DEPOSIT and send the cur- 
rent balance to that form. Calls to the FMS status-checking function appear 
at the end of these statements. 


12000 DEF FN.MAKDEP 
12050 CALL FDYV$CDISP ¢ ‘DEPOSIT’ ) \ C=FN.GETSTA 
12065 CALL FDVS$PUT ( STR#( BALANCEZ )+ ’CURBAL’ ) \ C=FN.GETSTA 


Statements 12125 and 12130 define two variables: DEP.AMT$, which rep- — 
resents the amount of the deposit made; and DEP.MEMO§, which repre- 
sents the deposit memo. In these statements, the SPACE$ function is used 
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to pre-extend DEP.AMT$ and DEP.MEMO$. These string variables must 
be at least as long as the return values expected. Thus, BASIC string varia- 
bles must be pre-extended to that length before being passed by the Form 
Driver. The SPACE$ function pre-extends strings by giving them a specific 
number of spaces. 


> DEP.AMTS = SPACE$(6) 
O DEP.MEMO$ = SPACE$(35) 


1212 
1213 
Statements 12135 and 12140 use the FDV$GET call to request the operator 
to enter data into the fields DEPOSIT and MEMO and then to return those 
values to variables DEP.AMT$ and DEP.MEMOS$. 


12135 CALL FDYV$GET ( DEP.AMT$»s TERMINATORZ» ‘DEPOSIT’ ) 
12140 CALL FDYSGET ( DEP.MEMO%$+ TERMINATORZ+» ‘MEMO’ ) 


Statement 12155 updates the checking account’s current balance, repre- 
sented by the variable BALANCE%. 


12155 BALANCE% = BALANCEZ + VAL ( DEP.AMTS ) 


Statement 12160 uses the FDV$PUT call to display the updated current 
balance in the field NEWBAL and then to call the FMS status checking 
function. 


12160 CALL FDV$PUT( STRS( BALANCEZ ), ‘’NEWBAL’ ) \ C=FN.GETSTA 


Statement 12165 uses the FDV$PUTL call to display a message that the 
deposit has been made. | 


127165 CALL FDV$PUTL( ‘’Derposit made - press RETURN or ENTER to continue’ ) 


Statement 12170 uses the FDV$WAIT call to pause and wait for the opera- 
tor to press RETURN to continue. Statement 12175 ends the subroutine. 


12170 CALL FDVSWAIT 
12175 FNEND 


5.2.8 Coding Subroutines VUEREG and VUEACT 


These two subroutines are stubs in the subset. They display the message 
that the subroutines are not implemented and then return to the menu, as 
in the functions of subroutine WRITCH. The statements for both 
subroutines follow: | 


13000 DEF FN,VUEREG 

13005 CALL FDVSPUTL ( ‘View register not implemented yet’ ) 
13010 CALL FDVSWAIT 

13015 FNEND 

14000 DEF FN.VUEACT 

14005 CALL FDV$PUTL ( ‘View account not implemented yet’ ) 
14010 CALL FDOVSWATT 

14015 FNEND 
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5.2.9 Coding Subroutine GETSTA 


GETSTA, a subroutine called frequently throughout the subset, checks the 
current FMS status and diagnoses any errors. Providing a status-checking 
subroutine in your FMS applications is good programming practice. If an 
error condition exists, this subroutine prints a code for the specific error 
condition. (See the VAX-11 FMS Form Driver Reference Manual for a list 
of the codes.) 


The GETSTA subroutine does the following: 


L 
2. 


Issues the FDV$STAT call. 


If the status code is greater than 0, the last call was successful, so 
control returns to the statement following the call to GETSTA. If the 
status code is equal to or less than 0, the FDV$DTERM call is executed, 
and codes are printed for both the FMS and the RMS (Record Manage- 
ment System) status. RMS returns any file or system operation error 
codes to the Form Driver. For more details on RMS, see the VAX-11 
FMS Form Driver Reference Manual. 


Terminates the subset application. The END statement, number 15999, 
is the last statement in the program. Control always passes to this 
statement. If the previous Form Driver call does not yield an error, 
control always branches back to the statement following the GETSTA 
function call before the END statement is reached. 


The GETSTA subroutine uses two Form Driver calls: FDV$STAT and 
FDV$DTERM. 


Returning the Status from the Last Call — FDV$STAT 


The FDV$STAT call returns the status for the last Form Driver call 
executed. The FDV$STAT call has the following format: 


FDV$STAT ( status [,iostat] ) 


The argument status represents a numeric code for the last Form 
Driver call executed, and iostat represents a numeric RMS status code 
for detailed information when the STATUS value is —4 or —18. 


Detaching the Terminal — FDV$DTERM 


At the end of an application, the FDV$DTERM call is used to detach 
the operator’s terminal from the application program. The call also 
cleans up the terminal for use by other programs. The FOV$DTERM 
call has the following format: 


FDV$DTERM ( tea ) 


The argument tca represents the area of memory set aside for the 
Form Driver workspace. 
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Coding the Body of GETSTA 


Statement 15025 uses the FDV$STAT call to return the FMS and RMS 
status codes after the last call executed. The FMS status code is represented 
by FMSSTATUS%, and the RMS status code is represented by 
RMSSTATUS%. 


15000 DEF FN.GETSTA 
15025 CALL FDYSSTAT ( FMSSTATUSZ+s RMSSTATUSZ } 


Statement 15030 returns control to the statement following the GETSTA 
call should FMSSTATUS% reveal no error conditions. Otherwise, control 
passes to statement 15730, which uses the FDV$DTERM call to detach the 
terminal. 


15030 IF FMSSTATUSZ > 0 THEN FNEXIT 
15730 CALL FDVSDTERM ( TCAZ ) 


Statements 15735 to 15745 print the error codes in FMSSTATUS% and 
RMSSTATUS%. Statement 15747 contains the STOP instruction, and 
statement 15750 ends the status-checking function. 


15735 PRINT "FDY ERROR." 

15740 PRINT ""»"FMS STATUS:" +sFMSSTATUSZ 
15745 PRINT "">"RMS STATUS: ">RMSSTATUSZ 
15747 STOP 

15750 FNEND 

15999 END 


NOTE 


Although FMS supports the standard VMS Run-Time Li- 
brary error-reporting procedures, the procedure used for indi- 
cating an error condition in the Sample Application and the 
subset application does not conform to the VMS conventions. 
For more details on error-reporting procedures, see the 
VAX-11 FMS Form Driver Reference Manual. 


You have now entered all the statements for the subset a Chap- 
ter 6 tells you how to compile, link, and run this program. 
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Chapter 6 
Compiling, Linking, and Running an Application 


As you read this chapter, you will learn how to create an executable image 
of the Sample Application subset that you prepared in Chapter 5. Figure 

- 6-1 shows the steps in the FMS application development cycle that are 
covered in this chapter. 















Main program 
object module 





Form Driver 





Executable 
image 


Form library 
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Figure 6-1: FMS Application Development Cycle 
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6.1 Compiling the Subset 


To compile the subset application, type the following command: 


$ BASIC SUBSET/LIST 


If you want to create the subset application in a language other than 
VAX-11 BASIC, consult the VAX—11 FMS Language Interface Manual. 


6.2 Linking the Subset 


Before you begin this step, check with your system manager to verify that 
the Form Driver library has been installed in the VMS system library. If 
this has been done, type the following command to link the subset object 
module: 


$ LINK SUBSET 


By default, VMS scans the system library to link the appropriate Form 
Driver library modules with the subset object module. 


6.3 Running the Subset 


To run the subset, type the following command: 


$ RUN SUBSET 


6—2 Compiling, Linking, and Running an Application 


Chapter 7 
Programming Features 


FMS can simplify your programming and can make forms more attractive 
and more useful. Four such features of FMS are discussed in this chapter: 


e Indexing 
¢ Scrolling 


e Named Data 


® User action routines 


This chapter describes these features in detail and lets you see how they 
are used in the Sample Application subset. In this chapter, you will create a 
subroutine, named VUEREG, for the subset and a check register form, 
REGISTER, in which you will incorporate these features. You can then 
rebuild the subset application and verify that each feature performs 
correctly. 


The VAX—11 FMS Form Driver Reference Manual describes other program- 
ming features that FMS offers. 


7.1. Indexing 


Indexing simplifies creating and accessing fields that are identical. Indexed 
fields have the same name and attributes and are distinguished by indexes, 
much like an array. Your application can access these indexed fields in any 
order. Indexing also simplifies the procedure of assigning attributes to 
identical fields. 


In the exercise that follows, you will learn about indexing by implementing 
it in the check register form, REGISTER. You will first be guided through 
the creation of REGISTER. You will then index the four fields in 
REGISTER. 


The following image is the REGISTER form from SAMP, the form in which 
you can see a register of the checks written and deposits made. 


CHECK REGISTER — THE ACCOUNT HISTORY 


Chk. Deposit Check New 
No. Date Check Payee or Deposit Meno Amount Amount Balance 


This Session: Starting Balance: $ 361.30 
Total Deposits: $ .0 
Total Checks: $ .0 
Current Balance: $ 361. 30 


To scroll through the check register, press UPARROW or DOWNARROW. 
To return to the menu, press RETURN. 





As you look at the form, note the following: 


1. The title, CHECK REGISTER — THE ACCOUNT HISTORY, is cen- 
tered on line 2 and is in double-wide characters. 


2. The column heads for the scrolled area are located as follows: 


Chk. No. Chk., line 5, column 2; No., line 6, column 2 

Date Line 6, column 8 

Check Payee Line 6, column 17 

Deposit Amount “Seat line 5, column 54; Amount, line 6, column 
Check Amount Check, line 5, column 63; Amount, line 6, column 63 
New Balance New, line 5, column 72; Balance, line 6, column 72 


3. Horizontal lines, created by the DRAW function, extend from columns 1 
to 79 on lines 7 and 14. Vertical lines extend from columns 1, 6, 16, 53, 
62, 71, and 79 to the two horizontal lines. 


4, The scrolled area has six lines. You will create this scrolled area in 
Section 7.2. 


5. Below the scrolled area is a summary of the check register figures. This 
Session: begins in line 15, column 22. Starting Balance: begins in col- 
umn 37. The field begins in column 56 and contains six characters and 
a decimal field-marker character. The field-validation character used in 
this field is 9, indicating that only numerals are to be accepted in this 
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field. This field’s attributes are Display Only, Right Justified, Zero Fill, 
Zero Suppress, and a zero (0) Clear Character. 


The remaining summaries — Total Deposits, Total Checks, and Cur- 
rent Balance: — appear directly below, and the fields are identical to 
the field next to Starting Balance:. These summary fields are display 
only and will, along with the Starting Balance field, be indexed. 


The background text at the bottom of the screen is in a box that occu- 
pies lines 20 to 23, from columns 14 to 80. 


7.1.1 Create REGISTER 


Invoke the Form Editor and create the form REGISTER, following the 
same steps you used in Chapter 3. 


E 


From the menu, go to the Form phase. Assign a white screen back- 
ground. 


Go back to the menu and then go to the Layout phase. Now create the 
form according to the design just discussed. Leave the scrolled area 
blank for now. You will draw in the lines after you have created the 
scrolled area. 


In the Assign phase, you assign indexing attributes to the summary 
fields in the middle of the form. The procedure for assigning these at- 
tributes follows. 


7.1.2 Assign Indexing Attributes 


Note that the four fields have identical attributes. Follow the steps below to 
index these fields: 


1. 


As you assign attributes to the Starting Balance field, assign the name 
SUMMARY. 


In the field next to Index Value, type 1, indicating the first in a set of 
indexed fields. Note that 1 appears in the blank below Index Value, 
captioned of. This blank shows how many fields are in the set of in- 
dexed fields. 


Assign the Display Only, Right Justified, Zero Fill, Zero Suppress, and 
zero (0) Clear Character attributes. 


Press RETURN to assign attributes to the next field. 


For the field’s name, again type SUMMARY. Assign the same attrib- 
utes you assigned to the first field you created. Note that after you 
press TAB when you assign the field name, the Index Value and Index 
Count blanks are automatically updated. Both blanks contain the value 
2. If you do not assign the same attributes that you assigned to the first 
field you created, the Form Editor signals you with an error if you press 
RETURN. 


Repeat steps 4 and 5 until all four fields are indexed. 
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7. Return to the menu and type EXIT. 


FMS provides an alternative to the procedure listed above: 
1. While in the Layout phase, create the first field to be indexed. 


2. Move the cursor into the field you just laid out and press GOLD 
FLDATR. 


Assign the name, SUMMARY. 
4. In the field next to Index Value, type 1. 


Assign the Display Only, Right Justified, Zero Fill, Zero Suppress, and 
zero (0) Clear Character attributes. 


5. Duplicate the field you just created four times, using the following pro- 
cedure: : 


e Move the cursor to a character position in the Summary field, SUM- 
MARY. 


e Press CUT. 
e Press GOLD PASTE to replace the field you just cut. 


e Move the cursor to the location where you want to place the second 
indexed field: line 16, column 56. 


e Press GOLD PASTE. 


e Repeat the previous two steps until all four fields have been pasted 
into their appropriate locations. The Form Editor automatically up- 
dates their index values and assigns the same attributes assigned to 
the first field in the indexed set. 


6. Return to the menu and exit. 


When you are finished with the Layout, Form, and Assign phases of creat- 
ing REGISTER, exit from the Form Editor. 


7.1.3 Manipulate Indexed Fields in the VUEREG Subroutine 


In this section, you will write the statements required to manipulate the 
indexed fields. The statements in VUEREG do the following: 


1. Display the check register form, REGISTER, that you just created 


2. Use the FDV$PUT call to assign numeric values to the four indexed 
fields 
NOTE 
Make sure that you delete statements 13005, 13010, and 
13015 that you have already entered for the VUEREG sub- 


routine. During run time, those statements display a mes- 
sage indicating that VUEREG is not implemented. 
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In the VUEREG subroutine, the values to be sent to the indexed fields have 
been established in the main body of the program. These values are the 
following arbitrary figures: 


SBALANCE% The starting balance: $503.75 

TOTPAY% The total amount written in checks: $213.45 
TOTDEP% The total amount of deposits made: $1123.23 
BALANCE% The current balance 


The statements you are about to write use the BASIC STR$ function to 
make character strings of the values to be sent to the indexed fields. 


Using an editor, type the following statements to display REGISTER and to 
assign values to the indexed summary fields: 


13047 CALL FDVSCDISP ( ‘REGISTER’ ) 

13050 CALL FDVS$PUT (¢ STR#( SBALANCEZ )+ ‘SUMMARY’, 1% ) 
13055 CALL FDOV$PUT ( STR#( TOTDEPAZ )+ ’SUMMARY’+ 2% ) 
13060 CALL FDVSPUT ( STRS( TOTPAYZ )+ ‘SUMMARY’>s 3% ) 
13065 CALL FDVSPUT ( STR#( BALANCEZ )+ ‘’SUMMARY’s 4% ) 


In the sections that follow in this chapter, you will be adding statements 
and features to VUEREG and to REGISTER. 


7.2 Scrolling 


In Chapter 2, you saw how the check register form, REGISTER, in the 
Sample Application program used scrolling. Scrolling lets you display and 
edit a list of data that is too long to fit on the screen at one time. 


The area of the form that displays the list of checks written is the scrolled 
area. When REGISTER first appears on the screen, the cursor is on the 
bottom line of the scrolled area. If you press DOWNLINE once, the list 
scrolls forward one line. The line that was at the.top of the list disappears 
from the screen, and a new line appears at the bottom of the list. The cursor 
is still on the bottom line of the window. 


If you press DOWNLINE several times, you reach the last item in the list. 
When the cursor reaches the end of the list, the following message appears 
at the bottom of the screen: 


Last line of register 


If you press UPLINE, the cursor moves up the list. Not until it reaches the 
top of the list does the list begin to scroll. 


When a list of data appears in the scrolled area on a form, the Form Driver 
is aware only of the lines that appear on the screen. The application is 
responsible for moving the list of data as necessary. 


The application must keep track of pointers to the following items to exe- 
cute scrolling: 


e The last item in the list of data 
e The item that appears at the top of the scrolled area 


e The bottom line in the scrolled area 
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Two Form Driver calls are used in the Sample Application to support scroll- 
ing: 


FDV$PFT Process field terminator 
FDV$PUTSC Output data to current line of scrolled area 


You will now create the scrolled area in REGISTER and write the subrou- 
tine in the Sample Application that executes the scrolling. 


7.2.1 Complete the Check Register Form, REGISTER 


Before you continue with this exercise, make sure that you have completed 
the exercises in Chapter 3 and the indexing exercise in Section 7.1.3. 


First, examine the design of the scrolled area in the REGISTER form: 


Chk. Deposit Check New 
No. Date Check Payee or Deposit Memo Amount Amount Balance 


15-HAR-G2 | Interest on National Coal bond 





Note the characteristics of the scrolled area: 


1. The scrolled area has six lines, and each line has six visible fields. Each 
field is display only. 


2. The first field, NUMBER, begins in line 8, column 2, and can have up to 
four characters. 


3. The second field, DATE, begins in column 7, but does not use the Date 
function. Instead, this field has the following field picture: XX-XXX- 
XX. If you were to use the Date function to create a field picture for this 
field, the Form Driver would display only the current date in this field, 
not the date representing the day of the transaction. 


4. The third field, PAYMEM, has 35 characters, starting in column 17 and 
extending to column 51. 


5. The fourth field, DEPOSIT, starts in column 54 and has six characters 
and a period field-marker character. This field has the Display Only, 
Right Justified, Zero Fill, Zero Suppress, and zero (0) Clear Character 
attributes. 
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6. The fifth field, AMTPAY, starts in column 63 and has the same charac- 
teristics as DEPOSIT. This field has the Display Only, Right Justified, 
Zero Fill, Zero Suppress, and zero (0) Clear Character attributes. 


7. The sixth field, BALANCE, starts in column 72 and is identical to the 
DEPOSIT field. This field has the Display Only, Right Justified, Zero 
Fill, Zero Suppress, and zero (0) Clear Character attributes. 


A seventh field exists in this form. Unlike the other fields, this field, lo- 
cated in column 80, is a dummy field. Scrolled lines should have at least 
one readable field — a field that is not display only — if you wish to place 
the cursor in each scrolled line. You can do this by placing a dummy field in 
each scrolled line. Each scrolled line, therefore, has this seventh field, 
named FAKE. It has the No Echo attribute and is never used by the appli- 
cation. FAKE provides only a means of placing the cursor in a scrolled line 
and of receiving a terminator for input. 


All fields in the scrolled area use only the X field-validation character. 
Since all these fields, except FAKE, are display only, the X field-validation 
character is all that is necessary. FAKE also uses X; thus, during run time, 
the subset application ignores any characters that may be entered. 


When the Sample Application runs and REGISTER appears on the screen, 
the cursor is in this dummy field. The dummy field is the field from which 
the Form Driver retrieves the field terminator to begin scrolling. 


To add a scrolled area to REGISTER, invoke the Form Editor and do the 
following: 

1. Type LAYOUT to enter the Layout phase. Move the cursor to line 8. 
2. Press GOLD FIELD. 


3. Type in the field-validation characters for the field NUMBER, as noted 
in this form’s design. 


4. Lay out the remaining six fields, all with the X field-validation charac- 
ter. Remember that the field FAKE does not have a column head and 
that it consists of a single X field-validation character. 


Press SCROLL. 
Press DOWNLINE. Note that the last line you laid out is replicated. 


Press DOWNLINE four more times until you have the six lines for the 
scrolled area. | 7 
8. Press ENDSCROLL. 


With the cursor in any line of the scrolled area, try to change one of the 
fields. Note that the change is replicated in each line in the scrolled 
area. It is thus easy for you to edit the lines in the scrolled area. 


10. When you are done with the scrolled area, draw in the lines around and 
through the scrolled area, as described in Section 1.1. 
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11. Exit from the Layout phase by pressing GOLD MENU to return to the 
menu. 


12. Type ASSIGN to enter the Assign phase. 


13. When in the Assign phase, note that you assign attributes to the fields 
in only one line of the scrolled area. Since all lines in the scrolled area 
must be identical, it is not necessary to assign attributes to the fields in 
every line in the scrolled area. 


14. Press GOLD MENU to return to the menu and exit. 


7.2.2 Insert REGISTER in SUBSET.FLB 


You must now place REGISTER in the form library, SUBSET.FLB. To do 
this, use the following command: 


$ FMS/LIBRARY/INSERT SUBSET 


The Form Librarian responds with the following prompt: 


~Input Files: 
Type the name of the form you just created, REGISTER. 


7.2.3 Writing the Statements that Support Scrolling 


In this section, you will write the statements required to support scrolling 
in the check register form, REGISTER. Before examining the scrolling 
statements, look at the flow of control for the VUEREG subroutine (see 
Figure 7-1). The form REGISTER is called and displayed by the SAMP 
subroutine VUEREG. | 
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Figure 7-1: Flowchart for the VUEREG Subroutine 
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The data to be scrolled is in an array, REGARRAY$. The application pro- 
gram, not the Form Driver, must keep track of which lines in REGARR- 
AY$ are in the scrolled area. The lines in REGARRAY$ that are mapped to 
the scrolled area appear in a window (see Figure 7—2). The process of scroll- 
ing can be thought of as mapping this window to the scrolled area on the 
terminal. 


Data List 
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Scrolled Area 
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Figure 7-2: Mapping a Window to a Scrolled Area 
NOTE 


In the Sample Application, REGARRAYS$ is in a data file and 
must go through a series of processes before it can be scrolled 
on to a terminal screen. In the subset application, we will 
simplify REGARRAY$’s data structure by assigning it 10 
specific items in subroutine INACCT. Before continuing with 
this exercise, edit SUBSET.BAS and add the following state- 
ments to INACCT that make up REGARRAY$. Use the DIM 
statement at the beginning of SUBSET.BAS to assign the 
array REGARRAY$ a size of 10 bytes. 


Edit SUBSET.BAS and make the following statement the first statement of 
the program: 


100 DIM REGARRAYS ( 10 ) 
Add the following statements to INACCT to compose make up array REG- 


ARRAY$. (The numbers above the statements show the exact column posi- 
tions of the data.) 


1 9 26 69 76 82 

| | | | | | 

4025 REGARRAYS(1)2=° ISMAR82Interest on National Coal bond 050000 50000” 
4030 REGARRAY8(2)=” 115MAR82Jack Dewar 1000 49000° 
4035 REGARRAYS$(3)=” 230JUN82LoUuise Phipps 2000 47000’ 
4040 REGARRAYS(4)=2” 314JUL82Townsend Fabrics 25900 220007 
4045 REGARRAYS$(5)=’ 430JUL82Channel 42 5000 17000% 
4050 REGARRAYS(6)=” 31 AUG82Paycheck 030000 47000° 
4055 REGARRAYS§(7)=” Si2SEP82FoureStar Auto 1543 45457° 
4060 REGARKRAYS(8)=” 6 40CTS82Mary Johnson 4450 41007” 
4065 REGARRAYS$(9) 2” 7 IFEBS3Cory Advertising Agency 5002 36005” 
4070 REGARRAYS(10)=” O4FEBS3Pegasus Equestrian Center 000125 36130° 
4075 LASTREGNUM$=10 
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To perform scrolling, VUEREG maps a section of REGARRAY$ to the 
scrolled area. 


Display REGISTER 
The first five lines of the VUEREG subroutine do the following: 


¢ Declare integer constants for the keypad keys ENTER, DOWNLINE, and 
UPLINE. 


e Issue the CDISP call to display the REGISTER form. 


e Display the summary balance figures. (These statements appear in the 
exercise on indexing, but are repeated here.) 


The first statement of VUEREG declares integer constants that represent 
the keypad keys the operator can press while REGISTER is displayed. 


130600 DEF FN.VYUEREG 
13001 DECLARE INTEGER CONSTANT B: 


FDOYSKUFTLUNTR = 0% ! RETURN or ENTER R: 

FOVSKUFTUSFW = 8% ' DOWNLINE (scroll forward) g 

FOVSKLUFTUSBK = 9 ! UPLINE (scroll backward) 
NOTE 


VAX-11 BASIC requires you to declare in the main program 
the integer constants representing each keypad field termi- 
nator. Some other languages that FMS supports permit you 
to use include or require files that contain these integer con- 
stants. 


Enter the following lines to perform the initial display and setup of REGIS- 
TER. Note that the FDV$PUT call uses indexing to display the summary 
figures. 


13047 CALL FDYV$CDISP ( ’REGISTER’ ) 

13050 CALL FDYVSPUT ( STR#( SBALANCEZ )+ ‘SUMMARY’, 12% ) 

13055 CALL FDYSPUT ( STR&( TOTDEPZ )+ ‘SUMMARY ’s 2% ) 

13060 CALL FDYSPUT ( STR&( TOTPAYZ )+ “SUMMARY ’s 3% } 

13065 CALL FDVS$PUT ( STR#( BALANCEZ )+ “SUMMARY ’s 4% ) 
NOTE 


If you have completed the section on indexing, you do not 
need to enter the statements above. 


The subroutine sets the variable NSCROL% to represent the number of 
lines in the scrolled area (6). 


13085 NSCROL% = 6% 
Initialize Two Scrolling Pointers 
The next two statements establish pointers to two lines: 


e A subscript in REGARRAY$ corresponds to the top line in the scrolled 
area — MINWINDOW%. MINWINDOW% is initialized to 1. 
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e A subscript in REGARRAY$ corresponds to the line the cursor is 
on — CURLINE%. CURLINES% is also initialized to 1. 


13135 MINWINDOWZ 1 


13140 CURLINE* i 


Output a Data Line into the Scrolled Area — FDV$PUTSC 


The FDV$PUTSC call sends the current line of the window to the 
scrolled area on the screen. The first line from REGARRAY$, the reg- 
ister array in the Sample Application, is sent to the first line in the 
scrolled area, using the FDV$PUTSC call. When the FDV$PUTSC call 
is issued, the entire line to be output is referenced by a single field 
name. This field can be any field in the line. The field also identifies 
which scrolled area to use, since a form can have more than one 
scrolled area. In this example, the line to be scrolled is referenced by 
the field NUMBER, the first field in each line in REGARRAY$. 


The FDV$PUTSC call has the following format: 
FDV$PUTSC ( fldnam, fidval ) 


The argument fldnam represents a field name in the line to be 
scrolled, and fldval represents a variable name containing the value of 
the line to be scrolled. 


Enter the following statement appearing in VUEREG to send the first line 
in REGARRAYS$ to the scrolled area on the screen: 


i3145 CALL FDYV$PUTSC (¢ ‘NUMBER’:s REGARRAY$(i) } 


Output the Remaining Lines in the Scrolled Area 


The subsequent statements in VUEREG occupy the remaining five lines in 
the scrolled area of the form REGISTER. Note the use of the variables 
MINWINDOW% and CURLINE%. Two additional variables are used in 
these statements: 


MAXWINDOW% A subscript of REGARRAY$ that corresponds to the 
bottom line of the scrolled area 


LASTREGNUM% __ A subscript of the last item in REGARRAY$ - 


Altering the Current Line — FDV$PFT 


This section of the subroutine uses the FDV$PFT call to increment the 
current line to the next line to be sent to the scrolled area. 


The FDV$PFT call has the following format: 
FDV$PFT ( [fldtrm,] [fldnam,] [fldval,] {nfldnam,] [,nfldidx] ) 
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The argument fldtrm represents the field terminator to be processed; 
fldnam is a field that identifies the scrolled area. The argument 
fldval represents the field values to be displayed if the screen is 
scrolled during the processing of the field terminator. The argument 
nfldnam represents the current field name after the call has been 
processed, and nfldidx represents the index of the the current field. 


Enter the following statements to send the first six lines of REGARRAY% 
to the scrolled area in REGISTER. Note that the PFT call is used here to 
update the current line for the Form Driver and that the variable CUR- 
LINE% is incremented simultaneously for the application source code. The 
PUTSC call then sends the current line to the scrolled area. 


13150 WHILE (¢ CURLINEZ < LASTREGNUMZ AND CURLINEZ% «© NSCROLZ ) 


13155 CURLINE? = CURLINEZ + 1 
13160 CALL FDYSPFT ( FDOVSK_FT_-SFHM+ ‘NUMBER’ ) 
13165 CALL FDOYSPUTSC ( ‘’NUMBER’»s REGARRAYS ( CURLINEZ ) ) 


13170 NEXT 
13171 MAXWINDOWA” = CURLINE 


Scrolling Forward and Backward 
The rest of the subroutine does the scrolling by performing the following 
flow of control: 


1. If the operator presses ENTER or RETURN, control returns to the 
menu. 


2. Ifthe operator presses DOWNLINE, the scrolled area scrolls forward. 
3. Ifthe operator presses UPLINE, the scrolled area scrolls backward. 


4. Ifthe operator presses any other key, the subroutine does nothing. 


The subroutine uses the FDV$GET call to get the operator input from the 
field FAKE$. The scrolling operation needs only the field terminator, not 
any particular value, from FAKE$. If the operator presses DOWNLINE, 
this routine branches to the SCRFWD subroutine. If the operator presses 
UPLINE, this routine branches to the SCRBAK subroutine. 


Enter the following statements, which make up the final section of 
VUEREG: 


13215 CALL FDV$GET ( FAKES» TERMINATORZ: ‘FAKE’ ) 
13220 WHILE NOT (TERMINATORZ = FDVSK_FT_NTR) 


13225 IF TERMINATOR’ = FOVSK_FTUSFW THEN C=FN.SCRFWD 
13235 IF TERMINATOR’ = FDVSK_FT_SBRK THEN C=FN.SCRBAK 
13245 CALL FDV$GET ( FAKES, TERMINATORZ» ‘FAKE’ ) 


13250 NEXT 
13255 FNEND 
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The Scroll Forward Subroutine — SCRFWD 
Figure 7-3 shows the flow of control in the SCRFWD subroutine. 
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Figure 7-3: Flowchart for the SCRFWD Subroutine 
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In summary, the SCRFWD subroutine works as follows: 


1. Check to see if the current line is pointing to the last line in the check 
register. If it is, print “Last line of register” at the bottom of the screen 
and go back to the body of VUEREG. If not, proceed with the subrou- 
tine. 


2. Ifthe cursor is not at the last line of the window, move the cursor down, 
increment CURLINE%, and return to VUEREG. If the cursor is at the 
last line of the window: ; 


e Increment MINWINDOW% and MAXWINDOW% 


e Scroll the lines in the window up one position and display a new line 
at the bottom of the window 


e Increment CURLINE% 
e Return to VUEREG 


Enter the following statements for the SCRFWD subroutine. Note the use 
of the FDV$PFT call. If scrolling occurs, FDV$PFT updates the current line 
and sends the new data line to the scrolled area. This special use of the 
FDV$PFT call makes a FDV$PUTSC call unnecessary in this routine. 


13500 DEF FN.SCRFWD 
13540 IF CURLINE% = LASTREGNUM% THEN 
CALL FDVS$PUTL ( ‘Last line of register’ ) 
FNEXIT 
13580 IF CURLINEX <> MAXWINDOWZ THEN 
CALL FDYV$PFT ( FDVSK_FT_LSFWs ‘NUMBER’ ) 
ELSE 
MINWINDOWZ = MINWINDOWZ + 1 
MAXWINDOWZ = MAXWINDOWYZ + 1 
CALL FDV$PFT ( FDOV$K_FT_SFW,s ‘NUMBER’, REGARRAYS ( MAXWINDOW,Z ) ) 
13585 CURLINEZ = CURLINEZ + 1 
13590 FNEND . 
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Scroll Backward Subroutine — SCRBAK 


The SCRBAK subroutine does the opposite of SCRFWD. Figure 7—4 shows 
the flow of control in the SCRBAK subroutine. 
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Figure 7—4: Flowchart for the SCRBAK Subroutine 
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The SCRBAK subroutine works as follows: 


1. Check to see if the cursor is at the top line in the REGARRAY$. If so, 
display the following message at the bottom of the screen and return to 
VUEREG: 


First line of register 


2. If the cursor is not at the first line in the window, move it up. If the 
cursor is at the first line of the window, move the window back one line 
and write the new first line to the first line of the scrolled area. (This 
action can be executed in one step by the FDV$PFT call.) 


3. Move the current line pointer, represented by CURLINE%, back one 
line. . 


Enter the following statements for the SCRBAK subroutine: 


13700 DEF FN.SCRBAK 
13740 IF CURLINE*? = 1 THEN 
CALL FDV#PUTL ( ‘First line of register’ } 


FNEXIT 
13780 IF CURLINEZ <2 MINWINDOWZ THEN 
CALL FDOVSPFT ¢€ FDOVSK_LFT_SBRK +s ‘NUMBER’ ) 
ELSE 


MINWINDOWZ = MINWINDOWZ - i 
MAXWINDOWA = MAXWINDOWZ - 1 
CALL FDOVSPFT (¢ FDVSK_LFT_SBR +s ‘NUMBER’+ REGARRAYS &. 
( MINWINDOWZ ) ) 
13785 CURLINEZ = CURLINEX” - 1 
13790 FNEND 


You have now completed the programming to implement scrolling in the 
subset application. Rebuild the subset application and verify that VUEREG 
performs correctly. 


7.3 Named Data 


Named Data provides a convenient way for you, the application program- 
mer, to store program parameters with the form instead of coding them into 
the program. By using Named Data, you can add forms and change existing 
forms without having to change the application program. 
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Named Data is data that is associated with a form but does not appear on 
the operator’s screen. Named Data exists in the workspace with the form. 
You associate Named Data to a form during the Form Editor Data phase. 
The data can be any string up to 80 characters and can be referenced by 
either name or index. In Figure 7—5, for example, an application could 
access NSTRING$ by referencing either VAL1, the name, or 1%, the index. 


INDEX NAME DATA 


NSTRING 


XSTRING 
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Figure 7-5: Data with Corresponding Names and Indexes 


Two calls retrieve Named Data from forms: FDV$RETDN and 
FDV$RETDI. 


FDV$RETDN 
The FDV$RETDN call has the following format: 
FDV$RETDN ( nmdnam, nmdval [,nmdidx] ) 


The argument nmdnam represents the name by which the data is 
referenced, nmdval represents a variable into which the Named Data 
is stored, and nmdidx represents the index of the data that is being 
returned. 


The following example retrieves from a form the value PSTRING$ by the 
name VAL2: 


CALL FDOV$RETDN ( ‘YAL2’,s PSTRINGS ) 


FDV$RETDI 


The FDV$RETDI call works the same way as the FDV$RETDN call 
except that the data is referenced by index. The FDV$RETDI call has 
the following format: | 


FDV$RETDI ( nmdidx, nmdval [,nmdnam] ) 


The argument nmdidx represents the index for the data to be re- 
trieved, nmdval represents the variable into which the data is stored, 
and nmdnam represents the name for the data to be retrieved. 


The following example returns the value PSTRING$ referenced by the 
index 2: 


CALL FDOV$RETDI ( 2%+ PSTRINGS ) 
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You will now add Named Data to the check register form REGISTER. You 
will then modify the subroutine VUEREG to incorporate the use of Named 
Data. 


The subroutine VUEREG uses Named Data to determine how many lines 
are in the scrolled area in REGISTER and then sets up the scrolled area 
accordingly. It is possible to change the size of the scrolled area in REGIS- 
TER and to support scrolling for that form without changing the scrolling 
statements in the subroutine. 


In this exercise, you will change the size of the scrolled area from six to five 
lines. Next, you will change the program to make the program pick up the 
size of the scrolled area from the form. Thus, later changes to the size of the 
scrolled area will not require changes to the program. 


Modify REGISTER 


Extract REGISTER from the library SUBSET.FLB and then edit REGIS- 
TER. You can do this in the single following command: 


$ FMS/EDIT SUBSET/FORM.NAME=REGISTER 


The screen clears and the Form Editor menu appears. Type DATA to enter 
the Data phase and press RETURN. A questionnaire appears on the screen 
(see Figure 7—6). 


Named Data 





Figure 7-6: Assigning Named Data 
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The numbers 1 to 5 are numbers for the items. Each item has a space for a 
name and a value. The cursor is in the name blank for the first Named 
Data item. Type the name Window and then press TAB. With the cursor on 
the second line, type 5 and press RETURN (see Figure 7-7). 





Figure 7-7: Assigning Named Data 


The menu appears on the screen. Type LAYOUT to enter the Layout phase. 
Press RETURN. REGISTER appears on the screen. Do the following: 


1. Move the cursor to the last line in the scrolled area. 
2. Press GOLD UNSCROL. 

3. Press GOLD INSERT. 

4, Press GOLD DELEOL. 

5. Press GOLD MENU. 

6. Type EXIT. 


Now update the form library SUBSET.FLB so that it contains the modified 
form, REGISTER. Do this with the following command: 


$ FMS/LIBRARY/REPLACE SUBSET/FORM_NAME=REGISTER REGISTER 


Modify the VUEREG Subroutine 


In VUEREG, the size of the scrolled area is established by the variable 
NSCROL%, which you assigned the value 6 during the exercise on scroll- 
ing. Using Named Data, you will retrieve a value for NSCROL% from the 
Named Data section in REGISTER. Since the value you supplied in the 
Named Data section was 5, NSCROL% will be assigned that value. 


Now you will edit VUEREG so that it uses the FDV$RETDI call to retrieve 
the value 5 and stores it in the variable NSCROL%. Using an editor, mod- 
ify VUERKG as follows: 


1. Where NSCROL% previously was assigned the value 6, you first ini- 
tialize NSCROLS to represent a blank. (VAX—11 BASIC requires you to 
pre-extend all string variables. In this case, you must create a single 

_ space for NSCROL$ so that it can later be set to represent a string 
value.) | 
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2. Add the FDV$RETDI call to retrieve the value 5, which was set up to 
be referenced by the index 1 when you modified the register form, REG- 
ISTER. The value 5 will be stored in NSCROL$. 


3. Use the BASIC VAL function to give NSCROL% the numeric value 5. 


Using an editor, go to the following line in VUEREG:;: 


13085 NSCROL’ = G% 


Delete that line and insert the following lines: 


13085 ‘“NSCROLS = ’ “ 
13090 CALL FDVSRETDI ( 1%+ NSCROLS ) 
13095 NSCROL%’ = VAL ( NSCROL ) 


Compile and link the subset one more time to test REGISTER and to see if 
the scrolled area has five lines. 


7.4 User Action Routines 


User action routines, or UARs, permit you to write routines that can be 
executed when the operator does one of the following: 


e Completes a field 
e Requests help 


e Presses a special key 


There are three types of UARs: 
e Field completion 

e Help 

e Function key © 


UARs are called directly by the Form Driver. With UARs an application 
program can execute a procedure while the Form Driver has control of the 
processing. In this way, a UAR supplements the Form Driver. 


A UAR is like any other subroutine except that it has no formal parameters 
associated with it. You associate a UAR with a form or a field during the 
Form Editor Assign phase. When you assign a UAR to a form or a field, you 
can specify a string of up to 80 characters to that UAR. The string acts asa 
parameter. 


A UAR can exist in a file by itself, or it can be included in the main 
program source file. Typically, UARs that can be used in a variety of appli- 
cations, called general-purpose UARs, are maintained in UAR libraries. 
UARs that are application-specific are commonly included with the main 
program. UARs can be compiled separately from the main program and 
need be bound with the FMS application only at link time. For more infor- 
mation on UAR libraries, see the VAX-—11 FMS Form Driver Reference 
Manual. 
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7.4.1 Field Completion UARs 


A field completion UAR is executed when a specific field in a form is com- 
pleted by any FMS terminator other than BACKSPACE, the terminator 
that moves the cursor to the previous field. In the Sample Application, for 
example, a field completion UAR is used in the WRITE A CHECK form. 
When the operator enters the amount of the check and presses TAB, a UAR 
verifies that the check amount does not exceed the current balance. If the 
operator writes a check for more money than is in the account, the terminal 
beeps, and the video attributes for the Current Balance field change to bold 
and blinking. 


If input to a field ends. with the BACKSPACE terminator or with any 
function key that is returned to the application program, the field comple- 
tion UAR is not called. Thus, the operator can always leave a field without 
having that field’s associated UAR executed. 


Another UAR in the Sample Application verifies that the operator enters a 
number in the range 1 to 5 for the choice in the menu. If the operator enters 
a number outside that range or a character, a message appears at the 
bottom of the screen, telling the operator to enter a number in the valid 
range. 


7.4.2 Help UARs 


You can use help UARs to provide an application-specific help facility. A 
pre-help UAR is activated when the operator presses HELP. Instead of 
processing a usual help request, the Form Driver passes control to the pre- 
help UAR. Pre-help UARs let the application take control of all help pro- 
cessing, field or form. Help UARs can also be useful in gathering statistics 
on how often help is requested for particular fields. Using help UARs, an 
application can provide more sophisticated on-line help. 


A post-help UAR is called after any other Form Driver help processing. 
That is, after all help, field and form, has been given and just before the 
Form Driver is ready to display the “No Help Available” message, the Form 
Driver calls the post-help UAR. 


7.4.3 Function Key UARs 


You can use a function key UAR to perform a procedure when the operator 
types a specific key. In the Sample Application, for example, a function key 
UAR appears with the menu to make keypad keys 1 to 5 act like numeric 
keys and to verify that the operator has pressed no keys other than keypad 
1, 2, 3, 4, 5, and keypad period. 


7.4.4 Creating a Sample UAR 


In this section, you will create a field completion UAR to verify input to a 
field. This UAR, entitled VALID1, is associated with the menu in the Sam- 
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ple Application. VALID1 checks to see if the input to the menu falls within 
the valid range 1 to 5. If the input is outside that range, VALID1 displays a 
message at the bottom of the screen and accepts another number. If the 
input is valid, control returns to the application. 


This exercise has five steps: 


1. Modify the form MENU to associate the UAR VALID1 with the Option 
field. 


2. Update the library file SUBSET.FLB so that it contains the modified 
menu form. 


3. Write the programming statements that make up VALID1. 
4. Create a UAR vector module. 
5. Use VALID1 to compile, link, and run the subset application. 


Modify the Menu Form 


Extract MENU from the library SUBSET.FLB and edit it, using the follow- 
ing command: 


$ FMS/EDIT SUBSET/FORM_NAME=MENU 


UARs are associated with a field during the Assign phase, so type ASSIGN 
to enter the Assign phase. 


When the Form Editor displays the first Assign phase questionnaire on the 
screen, type 3 to indicate that you wish to modify a specific field. When the 
Form Editor asks which field to modify, type OPTION. 


After the Form Editor displays the Assign phase questionnaire, press TAB 
until the cursor is in the field next to UARs? Type Y. (See Figure 7-8.) 


_ Autotab Right Justify _ Uppercase 
_ No Echo Fixed Decinal _ Must Fill 


_ Display Only ~ Zero Fill Response Required Clear Character _ 


Zero Suppress 7 Supervisor Only _- UARs? (Y,N) Y 





Figure 7-8: Assigning User Action Routines . 


The Form Editor responds by clearing the lower half of the screen and 
displaying a blank for naming UARs and for providing data strings for each 


Programming Features 7-23 


UAR. Since VALID1 is the UAR you wish to associate with this form, type 
VALID1 next to UAR Name: (see Figure 7-9). 


Checking Account Menu 


Choose Option (1-5S):. & 
{ Exit 
2 Write a check 
3 Make a deposit 
Field Completion User Action Routines 
Field Mane: OPTION 
i 


UAR Nane: 
Associated Data: 


2 ~—sCUAR Nane: 
Associated Data: 





Figure 7-9: Assigning User Action Routines 


Press TAB to move the cursor to the Associated Data field. Type the 
following: 


12345 


The string 12345 contains valid character for the Option field. You will see 
how this string is manipulated in the statements that make up VALID1. 


Press GOLD MENU to return to the Form Editor menu. Then type EXIT. 


Update SUBSET.FLB 


Update the library file SUBSET.FLB so that it contains the modified form 
MENU. Type the following command: 


$ FMS/LIBRARY/REPLACE SUBSET/FORM_NAME=MENU MENU 


Having associated a UAR with a form, you are now pene to write the 
statements that make up the body of the UAR. 


Write the Statements for VALID1 


The subroutine VALID1 can be compiled independently of the subset appli- . 
cation. Since VALID1 is a general-purpose UAR, create it as an individual 
file, naming it VALID1.BAS. After it is compiled, you can store it in a UAR 
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object library for future use. Details on creating and using UAR object 
libraries are supplied in the VAX—11 FMS Form Driver Reference Manual. 


Note that VALID1, like many other UARs in the Sample Application, is a 
general-purpose UAR. That is, you can use it in any FMS application to 
perform field validation of a single-character field without having to 
change the UAR. The only modification that must be made to use VALID1 
is in the Form Editor Assign phase when you specify the associated data 
string. 


The first statement in VALID1 establishes the codes the Form Driver uses 
to determine the results of the UAR upon completion. 


Enter the following statements. 


16005 FUNCTION INTEGER VALIDI 

16089 DECLARE INTEGER CONSTANT g: 
FOVSK_LUVYAL_ SUC = 1000, !Field completion success & 
FOV@K_UVAL_ FAIL = 1001 'Field completion failure 


The next four statements in VALID1 pre-extend the string variables into 
which FMS will return special values. Note that pre-extending string vari- 
ables is a requirement of the VAX-—11 BASIC language, not necessarily of 
other languages. The four string variables used in VALID1 are listed and 
described below. 


FRMNAM$ The name of the form in which the single-character field 
is used. In the Sample Application, the form is MENU. 


UARVAL$ A string that contains all the valid entries into the field in 
the menu. In the Sample Application, this string is 12345. 


FLDNAME$ The name of the single-character field. 


FVALUE$ The single-character value the operator has entered into 
the field. 


Enter the following statements, which use the BASIC SPACE$ function to 
pre-extend the string variables. 
16096 FRMNAM# = SPACE$(31) 
16097 UARVALS = SPACES$(8Q) 


16098 FLDNAMES = SPACE$(31) 
16099 FVALUES = SPACES$(1) 


The next statement uses the FDV$RETCX call to return the current con- 
text of the Form Driver to VALID1. The FDV$RETCX call returns the 
following values to VALID1: 


TCA% Address of the terminal control area 
WKSP% Address of the workspace 

FRMNAM$ Name of the current form 

UARVAL$ Character string associated with this UAR 
CURPOS% Cursor position within the current field 
FLDTRM% Field terminator used 

INSOVR% Character input mode (Insert or Overstrike) 


HELPNUM% #Number of times HELP has been pressed for the current 
field (nonzero only in a help UAR) 
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Although VALID1 returns all these values with the FDV$RETCX call, 
only UARVALS$, the variable that represents the UAR’s associated data, is 
used. The remaining values are ignored by this UAR. 


Enter the following statement to return special information to the UAR: 


16140 CALL FDVSRETCX ( TCAZs WKSPZ+ FRMNAMS+s UARVALS:s & 
CURPOS“Z+s FLDOTRM%Z+ INSOVRZA» HELPNUMZ ) 


Enter the following statement to retrieve the current field name and index. 


16145 CALL FDVSRETFN ( FLDNAMESs FINDEX% ) 


Using the name and index just retrieved by the FDV$RETFN call, the next 
statement uses the FDV$RET call to retrieve the value that the operator 
has entered into that field. 


Enter the following statement: 


16150 CALL FDOV$RET ( FYALUES» FLDNAMES, FINDEX? ) 


After issuing the FDV$RETCX, FDV$RETFN, and FDV$RET calls, 
VALID1 checks to see if the operator input, represented by FVALUE$, 
occurs in the string UARVAL$. VALID1 uses the VAX-11 BASIC function 
POS to do this. 


Enter the following statements: 


16185 IF POS( UARVALS:+ FYALUE$, 1) = 0 THEN 
VALIDI = FDVSKUUVAL_ SUC [Success 
ELSE 
CALL FDV@PUTL( ’Illegal value’ } 
VYVALIDI = FDVéK_UYAL_FAIL 
16210 FUNCTIONEND 


Create a UAR Vector Module 


The UAR vector module is a file, existing in object file format, that provides 
the necessary information to the linker to associate VALID1 to the menu 
form, MENU. When you create the UAR vector module, assign it the name 
SUBSTVCTR, using the following command: 


$¢ FMS/VECTOR SUBSET/OUTPUT=SUBSTYVCTR 


This command causes FMS to scan SUBSET.FLB for any occurrences of 
UARs. When FMS finds VALID1, FMS sets up a data structure that en- 
ables VALID1 to be called at the appropriate time. 
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Compile, Link, and Run 


Using VALID1 to execute the subset application, first compile the UAR, 
using the following command: 


$ BASIC VALIDI 


To link the subset application with VALID1, you must include the name of 
the UAR vector module, SUBSTVCTR. Type the following command: 


$ LINK SUBSET s+VALID1 »SUBSTYCTR 


After the subset is linked, run the application and verify that VALID1 
performs correctly. When the SUBSET menu appears on the screen, type a 
number outside the range 1 to 5. When you press RETURN, the following 
message should be displayed at the bottom of the screen: 


Tllegal value 


A field completion UAR returns one of the three values listed below to the 
Form Driver each time the operator enters a value into the field with which 
the UAR is associated (in this case, the Option field in MENU). 


FDV$K_UVAL_SUC The value entered by the operator was valid. The 
Form Driver should now call any additional 
UARs for this field. If the operator input is also 
found valid by any additional UARs, the operator 
input for this field is accepted. 


FDV$K_UVAL_END _ The value entered by the operator was valid. The 
Form Driver should not call any additional UARs 
for this field but should accept the operator input 

_ immediately. 


FDV$K_UVAL_FAIL The value entered by the operator was invalid. 
The Form Driver should signal the operator and 
request that input be reentered. 


When you run the subset application, VALID1 checks to see if your input to 
the menu is valid. If it is, VALID1 returns FDV$K_UVAL_SUC to the 
Form Driver, stating that the value entered was valid. Otherwise, VALID1 
displays the “Illegal value” message and returns FDV$K_UVAL_FAIL, 
telling the Form Driver to signal the operator and request that another 
value be entered. 
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Chapter 8 
Advice to New Users 


This chapter presents information that you may find useful when designing 
forms. Section 8.1 discusses elements of good form design. The text provides 
many helpful hints and techniques to use when designing forms. 


Section 8.2 explains how to use the video screen as a human interface. The 

_ primary goal of creating a good human interface in forms is to lower the 
operator error rate. Following the guidelines presented in this chapter can 
help you achieve this goal. 


Although this chapter provides many techniques and guidelines, this infor- 
mation is not the final word on form design. This chapter merely offers 
advice. 


8.1 Good Form Design 


The many books available on form design can give you good ideas for your 
FMS applications. Many of the ideas on preparing paper forms can be ap- 
plied to video forms. This section highlights principles of designing success- 
ful forms. Good form design consists of two goals: 


e To make forms that are easy to use 


¢ To lower the operator’s input error rate 


When designing forms, keep in mind the following: 
e Sort the information you wish to gather 

e Provide a good title for the form 

e Select good captions 

e Use check boxes 

e Use reverse video as a visual aid 


e Make the form self-instructing 


The sections that follow discuss these techniques in detail. 
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8.1.1 Sorting Information 


Before you sit down at the terminal to design a form, write down all the 
information that you wish to gather and to display in the forms. This infor- 
mation can be grouped into the following categories: 


e Key information (name, address, identification number, and so forth) 
e Instructions 


e Tables, lists, and supplemental data 


Next, approximate the length of each item appearing on the form. This list 
should tell how long the caption and the desired response should be. For 
example, an address usually requires three lines of about 40 characters 
each. 


The key information should appear in a conspicuous place on the 
forms — at the top center or top left, for example. Since such information 
is often used to identify a form, it needs to be readily visible. 


Decide which instructions to include on the form and which to put in help 
forms. Generally, self-instructing forms are more successful than those re- 
quiring separate instructions. 


Group information in sections of a form or on a separate forms. Use lines 
and boxes to separate groups of information that appears on the same form. 
Figure 8-1 shows a rough grouping of all the information required for a 
series of forms for a payroll application. 


Employee Data Salary information 
Home Address Wage Class 
Home Phone Salary Group 
Badge Number Current Salary 
Social Security Deductions 
Date of Hire 
Dependents 


Emergency Contact Supervisor Information 


Name Name 


Address Phone Number 
Phone Number 


Department Information Job Information 
Name Title 
Number Number 
Location Description 





MLO-061-82 


Figure 8-1: Sample Payroll Data 


8.1.2 Providing a Title 


A title should be as descriptive as possible of the purpose of the form. The 
location of the form title is a matter of personal choice. Top center is the 
usual position, although top left is also common. If a company name and 
address appear on the form, place them below the title. Highlight the title 
with a video attribute, such as bold or reverse, or use double-size or double- 
wide characters. 


Avoid using the word form in a title; it adds little to meaning. 
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8.1.3 Writing Good Captions 


When making up a form, use care in writing captions. Good captions can 
help to minimize data entry errors. It is important that captions and other 
words on a form be easy to understand. The few words you use in a caption 
must leave no doubt as to the desired response. Good captions result in: 


e Better answers, in less time 
e Less need for instructions and help 
e Easier maintenance of the form 


For example, in a date field, specify which date the operator is to enter: 
today’s date, effective date, termination date, delivery date, and so forth. 


8.1.4 Using Check Boxes 


Captions and check boxes can be set up to provide multiple-choice and 
yes/no sections on your forms. Using check boxes, or single-character fields, 
simplifies data entry and reduces the data entry error rate by providing 
answers from which the operator can select an appropriate response. 


When you have determined which answers are to have check boxes, you can 
then decide how to arrange them. The following are several ways to ar- 
range the answers for a question on marital status. 


Marital status Single []- Married []_ Single, head of household [J 
Married, but spouse filing separately [ 


Marital status Single im 
Married O 
Single, head of household CO 
Married, but spouse filing separately [ 
Marital status 1] Single 
[] Single, head of household 
[] Married 
C 


Married, but spouse filing separately 





Marital status 
[] Single [] Single, head [1] Married [] Married, but spouse 


of household filing separately 


The last two examples are easier to read and respond to than are the first 
two. 


With multiple-choice questions, check boxes should appear before the re- 
sponses. Indicate which character the operator should enter in the check 
box, such as an X. With yes/no formats, check boxes should appear after the 
responses, as follows: 


Married 
Employed 

USS. citizen 

Head of household 


ES 
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8.1.5 Using Reverse Video Screen Characteristics 


Reversing the screen characteristics can help to guide the operator’s eyes 
across a form. Reverse video can: 


° Separate sections of the form 
e Highlight sections of the form 
© Separate captions from fields 
© Give the illusion of a colored background 


e Give the form a pleasing appearance 


Note that VT100 terminals with the advanced video option provide three 
intensities with which to work: bold, light, and reverse video. — 


8.1.6 Providing Instructions 


Designing a form carefully reduces the need for lengthy instructions on 
how to fill it out. The only instructions necessary should say “Fill out Form 
XYZ.” If more instructions are necessary, make them easy to understand. 


Just as with captions, instructions should be easy to understand. Make sure 
that you explain the proper use of the form and describe its purpose clearly. 
Be careful not to overexplain simple items. 


Keep in mind that many operators do not read instructions carefully. For 
that reason, you should format and word instructions so that they can be 
scanned easily. In the example below, the instructions in list form are 
easier to follow than are those in paragraph form. 


Read the box at the top left of the screen before completing your answers. 
Answer all questions. Indicate yes or no responses where applicable. Press 
HELP if necessary. | 


1. Read the box at the top left of the screen before completing your 
answers. 


2. Answer all questions. 
3. Indicate yes or no responses where applicable. 


4. Press HELP if necessary. 
Instructions are most effective when they are close to the field or section to 


which they refer. If the captions are well chosen, few individual fields will 
need much explanation. 
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8.2 Use of the Video Screen 


You must take special considerations into account when designing forms 
for video display. This section presents techniques used in some of the more 
successful video displays. Specifically, this section discusses: 


e Data presentation 
e Screen layout 
e Form content 


e Recovery procedures 


8.2.1 How to Present Data 


- The section presents hints on presenting nonverbal information on a 
screen. Nonverbal information includes mostly numerical information, 
such as telephone numbers, part numbers, storage dumps, and so on. This 
section provides guidelines on presenting the following types of data: 


e Lengthy alphanumeric strings 
e Ordered data 
e Data lists 


e Punctuated data 


Lengthy Alphanumeric Strings 


Break down strings of alphanumeric characters into groups of three or four 
characters. 


Before After 
125ACA6740B45C00 125A CA67 40B4 5C00. 
5628CJ VTH4838TND 5628 CJVT H483 8TND 
ABBA34568794FV10 ABBA 3456 8794 FV10 


The FMS field-marker character for placing blanks in a field picture is B. 


Ordered Data 


Organize data so that it can be easily read and identified. In the example 
that follows, the numbers are arranged by size, from left to right across the 


screen. 

Before After 
12.4 15.34 3.1415 2.2 3.1415 4.5 
2.2 23.67 4.5 7.9 7.9 12.34 12.4 
34.2 82.1 12.34 15.34 23.67 34.2 


82.1 
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Data Lists 


When possible, list the data vertically. Use numbered lists only when you 
are listing items that can be selected. Do not use letters to alphabetize lists. 
Begin numbered lists with 1, not 0. As shown in the example below, names 
or words should be left justified; numeric lists should be right justified. 


1. Magtape 
2. Cassette 
3. Diskette 


4. Cartridge 
When listing numbers with decimal points, the decimal points should align. 


234.13 
34214.45 
2.02 
103.89 


With FMS you can use left- or right-justified fields to make the alignment 
easy. 


Indent subordinate items in vertical lists. 


MENU 
WRITE A CHECK 
MAKE A DEPOSIT 
VIEW CHECK REGISTER 
EXIT 
WRITECHECK 
DEPOSIT 


When providing items from which the reader is to make a selection, ar- 
range the items in alphabetical order if the list has more than seven items. 
If the list has seven or fewer items, put the more probable choices at the top 
of the list. 


Choose a language 
BASIC 
FORTRAN 
COBOL 
PASCAL 
APL 
LISP 
ALGOL 


Punctuated Data 


Avoid unnecessary punctuation. Use periods after item selection numbers 
and sentences. Abbreviations, mnemonics, and acronyms should not in- 
clude periods. Avoid using quotes to highlight words. Avoid hyphenating 
words. 
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8.2.2 Screen Layout 


This section presents guidelines on organizing groups of data on a video 
screen. 


One goal of organizing information on a screen is to provide a structure 
that the operator can identify. When an operator can identify a specific 
structure or a pattern in a set of forms, the forms are generally easier to 
understand and work with. 


Be consistent in your presentation of forms. One section of the form may 
always be used for instructions. Another section might be reserved for the 
title, and another section might contain fields for operator input. Establish 
a meaningful structure to a form, and use that structure in subsequent 
forms in the same application. 


You can use reverse video in portions of a form or set off sections with lines. 
Do not break the screen up into too many small sections, however, or the 
form will be cluttered and confusing. 


Use the following guidelines when formatting your information: 


e Separate paragraphs by at least one blank line. 


-@ When listing descriptions, advantages, alternatives, and so on, start each 
point on a new line. Put bullets (lowercase 0) or hyphens before each point 
to make the list visually appealing. 


With the Sample Application, you can 
Write checks 

Make deposits 

View the check register 

View the account data 


Experiment with the special graphics available in the RULE character 
set for different types of bullets. 


e In numbered lists, separate the number from the item by at least one 
space. 


e Limit the user’s choice to seven items for any one field. 


8.2.3 Communication with the Operator 


Feedback is critical in any type of communication. In an interactive video 
session, timely feedback is essential for the operator to feel confident with 
the application. An operator can become very frustrated with a program 
that fails to provide feedback about whether the program has been accept- 
ing any input. To assure the operator that input has been accepted as 
intended, make sure that your application provides meaningful, informa- 
tive messages. This section discusses two ways of providing operator feed- 
back: highlighting and messages. 
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Highlighting 


Highlighting the field into which the operator is entering input is an effec- 
tive way of showing which portion of the form is being worked on. FMS 
provides several attributes that can be used to highlight sections of forms. 
These attributes are discussed in Section 8.3. 


Messages 


Messages can prompt for more information, tell the operator what else to 
do, and diagnose an error condition. Messages should be concise and clear, 
stating only what the operator needs to know to continue. Also, messages 
should be positive rather than negative. For example, instead of saying 
“Tllegal value,” the message should say “Value must be in range 1 to 5.” 


8.2.4 Recovery Procedures 


From an operator’s viewpoint, being able to correct an error without having 
to go back to the beginning is most desirable in any application. Although 
feedback is necessary for operator recovery from an error, it is not always 
sufficient. Error messages try to tell how to recover from an error condition, 
but they cannot always direct the operator to the spot where the error 
occurred. 


Recovery procedures should detect an error condition as soon as possible. 
User action routines that check for correct input and return operators to 
locations where errors occurred provide an effective means of recovery. 
When preparing your application programs, try to incorporate as many 
thorough recovery techniques as possible. 


8.3 FMS Field Attributes 
The FMS field attributes are listed below. 


Autotab The Form Driver is to consider a field complete when 
the operator types the last character in the current 
field. Depending on the Form Driver call issued by 
the application program, the cursor moves immedi- 
ately to the next field without requiring the operator 
to press a field terminator key. 


Clear Character A character that appears in unfilled data positions in 
a field. A blank is the default. 


Display Only A field can display data, but the terminal operator 
cannot enter data. 


Fixed Decimal A field is all signed or all unsigned numeric and has 
a single decimal point (.) or a comma (,) as a field- 
marker character. 
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Must Fill 


No Echo 


Response Required 


Right Justify 


Supervisor Only 


Uppercase 


Zero Fill 


Zero Suppress 


Each character position in a field must be filled if 
any character is entered. This attribute is particu- 
larly useful with data such as telephone numbers 
and identification numbers, in which only a specific 
number of digits entered is meaningful. 


Input from the operator is not displayed on the 
screen. This attribute is most frequently used to keep 
passwords private. 


The operator must enter valid data into the field. 


The data entered is to be aligned at the right; the 
remainder of the field may be filled with leading ze- 
ros or spaces. 


A field is considered to be display only when this 
attribute is enabled for a terminal. Enabling and dis- 
abling supervisor-only mode is done by the applica- 
tion at run time. 


All alphabetic characters entered in a field are dis- 
played as uppercase characters and are also returned 
to the application as such. 


The field positions that do not contain data are re- 
turned to the program as zeros. 


The leading zeros of a value entered in a right-justi- 
fied or a fixed-decimal field are to be replaced with 
blanks. 
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Appendix 
Subset Application Listing 


130 

140 

1040 
1042 
1050 
1100 
1110 
1115 
1170 
11806 
1190 
1200 
1268 
1215 
1220 
1230 
4000 
4005 
4010 
4015 
4020 
4025 
4030 
4035 
4040 
4045 
4050 
4055 
4060 
4065 
4070 
4075 
4080 
4085 
3000 
3005 
53010 
3015 
3020 
9025 
5030 
3040 
S045 


DIM WORKSPACE% ere ee 
DIM TCAZ ( 3) 
CALL FDV$ATERM ( TCAZ ()+5 12%5 2% 


) 


CALL FDVSAWKSP ( WORKSPACE ()+ 2000% )\C=FN.GETSTA 
CALL FDV$LOPEN ( ‘SUBSET’, 1% ) \C=FN.GETSTA 


! 
MAIN MODULE 


| 
C 
C FN.MENU PROCESS MENU REQUESTS 
I 

{CLOSING PROCEDURE 

CALL FDVSLCLOS 

CALL FDVSDWKSP( WORKSPACEZ () ) 
CALL FDYVS$DTERM( TCAZ() ) 

GOTO 15999 

! 

DEF FN. INACCT 

SBALANCE’ = $0375 

TOTPAYS = 21345 

TOTDEP’ = 112323 

BALANCE’ = 141353 


FN. INACCT ! INITIALIZE ACCOUNT DATA 


REGARRAYS$(1)=7 ISMARBZInterest on National Coal bond O50000 


REGARRAY$(2)=/’ LISMARS2Jack Dewar 


REGARRAY$(3)=’ 230JUN82@Louise Phipps 
REGARRAY$(4)=/’ S14JULB2Townsend Fabrics 


REGARRAY$(3)=' 430JUL82Channel 42 
REGARRAY$(6)=’ 31AUGB2Paycheck 


030000 


REGARRAY$(7)='’ SI2SEP82Four-Star Auto 
REGARRAY$(8)=’ G 40CTB2Mary Johnson 
REGARRAY$(9)=' 7 1IFEBB3Cory Advertising Agency 


REGARRAY$(10)='’ QOdFEBSB3Pegasus Equestrian Center 000125 


LASTREGNUMZ=10 
FNEND 

! 

DEF FN.MENU 
!'MENU CHOICES 


! 1 => EXIT 

! 2 => WRITE A CHECK 

! 3 => MAKE A DEPOSIT 

! 4 => VIEW CHECK REGISTER 
! 5 => SHOW ACCOUNT DATA 
OPTIONS = ’ *% 

WHILE 1 = 1 


1000 


2000 
20000 
2000 


1543 


4450 
2002 


50000° 
ag000' 
A7000° 
22000! 
17000 
A7000° 
A5457° 
41007 ° 
36005 ° 
36130° 


3050 CALL FDV$CDISP( ‘MENU’ ) \C=FN.GETSTA 

9070 CALL FDV$GET( OPTIONS» TERMINATOR’: ‘OPTION’ ) \C=FN.GETSTA 
9075 ON VAL( OPTIONS ) GOTO 5082+ 5090, 5100, 3110, 5120 
5081 ! OPTION 1s: EXIT 


5082 FNEXIT 

9085 ! OPTION 2: WRITE CHECKS 

5090 C = FN-WRITCH \GOTO 5130 

5095 ! OPTION 3: MAKE A DEPOSIT 
3100 C = FN-«MAKDEP \GOTO 5130 

S105 | OPTION 4: VIEW CHECK REGISTER 
3110 C = FN.-VYUEREG \GOTO $130 

S115 ! OPTION S: VIEW ACCOUNT DATA 
5120 C = FN.VYUEACT \GOTO 5130 

9130 NEXT 

5140 FNEND 

S150 | 


11000 DEF FN.WRITCH 

11005 CALL FDV$PUTL( ‘Write a check - not implemented vet’ ) 
11010 CALL FDVSWAIT , 

11015 FNEND 

11020 |! 

12000 DEF FN.MAKDEP 

12050 CALL FDVS$CDISP( ‘DEPOSIT’ ) \C=FN.GETSTA 

12065 CALL FDV$PUT( STR#( BALANCEZ )»+ ‘CURBAL’ ) \C=FN.GETSTA 
12125 DEP.AMT$ = SPACES$(6) 

12130 DEP.MEMO$ = SPACE$(35) 

12135 CALL FDVS$GET( DEP.AMT$+» TERMINATORZ+ ‘DEPOSIT’ ) 

12140 CALL FDV$GET( DEP.MEMO$+ TERMINATORZ» ‘MEMO’ ) 

12155 BALANCEZ = BALANCEZ + VAL( DEP.AMTS$ ) 

°12160 CALL FDVS$PUT( STR#( BALANCEZ )+ ‘’NEWBAL’ ) \C=FN.GETSTA 
12165 CALL FDVSPUTL( ‘Deposit made - press RETURN or ENTER to continue’ ) 
12170 CALL FDVSWAIT 

12175 FNEND 

12180 ! 

13000 DEF FN.VUEREG 

13001 DECLARE INTEGER CONSTANT & 


FDV$K_FT_NTR = O+ &: 
FDV$K_FT_SFW = 8» &. 
FDOV$K_FT_SBK = 9 


13047 CALL FDV$CDISP( ‘REGISTER’ ) 

13050 CALL FDV$PUT( STR#( SBALANCE% )» ‘SUMMARY’: 1% ) 
13055 CALL FDOV$PUT( STR&( TOTDEP% )» ‘SUMMARY’»s 2% ) 
13060 CALL FDV$PUT( STR#( TOTPAY% )+ ‘SUMMARY’+ 3% ) 
13065 CALL FDV$PUT( STR#( BALANCE% )+ ‘SUMMARY’s 4% ) 
13085 NSCROLS = ’ ° 

13090 CALL FDV$RETDI ( 1%+ NSCROLS ) 

13095 NSCROL% = VAL ( NSCROL® ) 

13135 MINWINDOWZ = 1 

13140 CURLINEZ = 1 

13145 CALL FDV$PUTSC( ‘’NUMBER’»s REGARRAY$(1) ) 

13150 WHILE (¢ CURLINEZ < LASTREGNUM% AND CURLINEZ < NSCROLZ ) 


13155 | CURLINE% = CURLINE% + 1 

13160 CALL FDVS$PFT( FDOV$K_FT_SFWs ‘NUMBER’ ) 

13165 CALL FOV$PUTSC( ‘NUMBER’s REGARRAYS( CURLINEZ ) ) 
13170 NEXT 


13171 MAXWINDOWZ = CURLINE% 
13215 CALL FDV$GET( FAKE$+s TERMINATORA» ‘FAKE’ ) 
13220 WHILE NOT (TERMINATORZ = FOVS_FT_NTR) 


13225 IF TERMINATOR’ = FDOVS$K.FTSFW THEN C = FN.SCRFWD 
13235 IF TERMINATORZ = FDOVSK_FT-SBK THEN C = FN.SCRBAK 
13245 CALL FDV$GET( FAKES» TERMINATORZ»+ ‘FAKE’ ) 

13250 NEXT 

13255 FNEND 

13315 |! 
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13500 DEF FN.SCRFWD 
13540 IF CURLINEZ = LASTREGNUMZ THEN 
CALL FDOYVSPUTL( ‘Last line of register’ ) 
FNEXIT 
13580 IF CURLINEX <> MAXWINDOW% THEN 
CALL FDVSPFT( FDVSK_FTUSFW, ‘NUMBER’ ) 
ELSE 
MINWINDOWZ MINWINDOWZ + 1 
MAXWINDOWAZ = MAXWINDOWZ + 1 
CALL FDVSPFT( FDOVSK_LFT_SFW, ‘’NUMBER’s REGARRAYS( MAXWINDOWZ ) ) 
13585 CURLINEZ = CURLINEZ + 1 
13590 FNEND 
13595 ! 
13700 DEF FN.SCRBAK 
13740 IF CURLINEZX = 1 THEN 
CALL FOVS$PUTL( ‘First line of register’ ) 
FNEXIT 
13780 IF CURLINEZ <> MINWINDOWZ THEN 
CALL FOV#PFT( FOVSK_FT_SBK+ ‘NUMBER’ } 
ELSE 
MINWINDOWZ MINWINDOWZ - 1 
MAXWINDOWS MAXWINDOWA - 1 
CALL FDOVSPFT( FOVSK_FT_SBK» ‘NUMBER’, REGARRAYS( MINWINDOWZ ) } 
13785 CURLINEZ = CURLINEZ - 1 
13790 FNEND: 
13795 ! 
14000 DEF FN.VUEACT 
14005 CALL FDOV#PUTL( ‘View account not implemented yet’ ) 
14010 CALL FDVEéWAIT 
14015 FNEND 
14020 ! 
15000 DEF FN.GETSTA 
15025 CALL FDVSSTAT( FMSSTATZ+ RMSSTATZ ) 
15030 IF FMSSTATZ > 0 THEN FNEXIT 
15730 CALL FDYVS$DTERM( TCAZ() ) 
15735 PRINT "FDY ERROR." 
15740 PRINT ""s"FMS STATUS!" sFMSSTATZ 
15745 PRINT "">"RMS STATUS: " »sRMSSTATZ 
13747 STOP 
15750 FNEND 
15999 END 


The following listing is for the user action routine VALID1, which can exist as a 
separate file or in the same file as the subset application. 


16005 FUNCTION INTEGER VALIDI 

16089 DECLARE INTEGER CONSTANT g: 
FOV#KUUVALCSUC = 1000, !Field completion success & 
FOUSK_LUVAL_FAIL = 1001 !Field completion failure 


16096 FRMNAMS = SPACE$(31) 
16097 UARVALS = SPACE$(80) 
16098 FLDONAMES = SPACE$(31) 
16099 FVALUES = SPACES$(1) 


16140 CALL FOVSRETCX(TCAZ sWKSP% »>FRMNAMS »UARVALS sCURPOSZ sFLDTRMZ> & 
INSOVRZ sHELPNUMZ ) 


16145 CALL FDV$RETFN ( FLDNAME$+s FINDEX% ) 
16150 CALL FDV$RET ( FYVALUES» FLDNAMES, FINDEXZ ) 
16185 IF POS( UARVAL$» FVALUES» 1) > O THEN 
VYALID1 = FDOVSK_UVAL_SUC !Success 
ELSE 


CALL FDV#PUTL( ‘Illegal value’ ) 
VALID1 = FDV$K_UVAL_FAIL 
16710 FUNCT IONEND 
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Glossary 


Action Routine. 
See User Action Routine. 


Application Program 


A program that performs work specific to the needs of a particular group of people. 
An application program can be any program that is not part of the operating 
system. 


Argument 


In FMS, a variable or a value passed in a call to the Form Driver to specify the 
action of the call or to specify a variable to receive the results of an operation. 


Assign Phase 


In the Form Editor, a phase in which attributes, such as Must Fill or Response 
Required, are assigned to fields within a form. 


Attach Terminal 


To assign a terminal for the exclusive use by the application program. Contrast 
with Detach Terminal. 


Attributes 


Characteristics assigned to fields and forms. Must Fill, Response Required, Right 
Justified, and No Echo are attributes. 


Autotab Attribute 


A field attribute indicating that the Form Driver is to consider a field complete 
when the operator types the last. character in the current field. Depending on the 
Form Driver call the application program issues, the cursor moves immediately to 
the next field without requiring the operator to press a field terminator key. 


Glossary—1 


Background Text 


On a form, the displayed portion that cannot be modified by the operator. Contrast 
with Field Characters. 


Binary Form 


A file containing a single form description in binary format. A binary form’s de- 
fault file type is FRM. See Form Description. 


Blank Fill Attribute 


A field attribute specifying that field values returned to the application program 
are to contain ASCII spaces. Contrast with Zero Fill; see also Pad. 


Caption 
Background text, associated with a field, that identifies the field. 


Character 


A single letter, digit, or symbol used to represent information. 


Character Set 
A set of 94 graphics corresponding to the printable characters. 


Clear Character 


A character appearing in empty data positions in a field. A blank is the default. 
An underscore (—) most closely duplicates the appearance of a paper form. 


Cursor Position 


The place on the screen where the next character typed on a terminal keyboard 
will be displayed, indicated by the location of the cursor. 


Data Phase 


In the Form Editor, a phase in which Named Data items are associated with a 
form. See Named Data. : 


Data Positions 


Alterable character positions — within fields, the locations where an operator can 
type data or an application program can display information; within a field, the 
positions denoted by field-validation characters, not by field-marker characters. 


Default 


The value of an argument, field, or part of a command line assumed by a program 
if a specific value is not supplied by the user. For example, the default file type for 
a form library is .FLB. 
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Detach Terminal 
To free an attached terminal. Contrast with Attach Terminal. 


Display Only Attribute 


A field attribute indicating that the application program can display-a value on 
the screen for a particular field, but that the terminal operator cannot enter data 
there. 


End of Line 


In the Form Editor, the rightmost screen position on a given horizontal line; not 
the rightmost character in a string of text. 


End of Text 
In the Form Editor Layout phase, the rightmost character in a string of text. 


Exit Phase 


In the Form Editor, a phase in which the current form may be saved and the Form 
Editor terminated. 


Field 


On a form, a variable portion that can be modified by the operator and/or the 
application program; a field can contain field-marker characters, which cannot be 
modified. A field is defined by a contiguous string of field-marker and field-valida- 
tion characters and cannot exceed one line in length. 


Field Attributes 


Characteristics — such as Must Fill, Right Justified, and No Echo — assigned to 
fields. 


Field-Marker Characters 
Characters that are displayed within a field but that cannot be modified by the 
operator. These characters are used for clarity and readability of data in a field. 
Examples of field-marker characters are the hyphen (-) and the slash (/). These 
characters are not returned to the program as input by means of the FDV$GET 
call or written as output by means of the FDV$PUT call. See Field-Validation 
Characters. . 


Field Mode 


In the Form Editor Layout phase, the mode that lets you create and modify fields 
in a form. Only field-validation characters or field-marker characters can be en- 
tered in Field mode. Contrast with Text Mode. 
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Field Name 


A field attribute identifying each field within a form. Names are 1 to 31 characters 
long; the first character must be alphabetic. (The only nonalphabetic and nonnu- 
meric characters allowed are the dollar sign ($) and underscore (_).) 


Field Picture 


The appearance of a field as specified by its field characters. The picture describes 
both the valid contents of a field and its screen format. 


Field Terminator Code 
A value that represents a key that can be struck to complete input to a field. 


Field Terminator Key 


A key pressed by the operator to signal the completion of data entry to a field or a 
form. ENTER, RETURN, and TAB are field terminator keys; others can be defined 
by the application programmer. 


Field-Validation Characters 


Characters that define data positions within a field and that describe valid input 
for that position. The field-validation characters and the valid input associated 
with each are: 7 


Alphabetic 
Alphanumeric 
Signed numeric 
Any character 
Numeric 


OK Z2AY 


See also Field-Marker Characters. 


Field Value 


The contents of a field, excluding field-marker characters, as known by the Form 
Driver. Field values are stored as ASCII characters. 


Fill Character 


A character to be stored in the unfilled data positions of a field. The fill character 
is replaced by the clear character when the field is displayed. See Zero Fill and 
Blank Fill. 


Fixed-Decimal Attribute 


A field attribute indicating that a field is signed or unsigned numeric and has a 
period (.) or comma (,) as a field-marker character indicating the position of the 
decimal point. | 
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Form 


A collection of structured information displayed on the screen. At most, an FMS 
form consists of one screen of information. More than one form can be displayed on 
a screen at once. 


Form Application Aids 
The multifunction FMS component that does the following: 


e Converts binary form files to form descriptions 

e Creates COBOL data declaration files 

e Converts binary forms to object modules for use as memory-resident forms 
e Provides form descriptions and library file directory listings 


e Creates vector modules for user action routines 


Form Attributes 


Characteristics assigned to an entire form. Examples of form attributes are First 
Line to Clear, Last Line to Clear, screen background, and screen width. 


Form Description 


A collection of Form Language statements that define the attributes and informa- 
tion needed to create a form. A form description can be produced either by the 
/DESCRIPTION command, using an existing form for input, or with a text editor. 
The form description is suitable for translation into a binary form by means of the 
Form Language Translator. 


Form Driver 


A set of subroutines that interact with an application program to display forms on 
video terminals and to accept data entered by operators. 


Form Editor 


The FMS utility you use to create and modify forms through interactive sessions 
at a video terminal and during which the forms are displayed on the screen. 


Form Language 
The grammar for defining forms as an alternative method to using the Form 


Editor. Also the name of the language in which the forms are defined. 


Form Librarian 
The FMS component that creates and manipulates form libraries. 
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Form Library 


A file containing an organized collection of one or more form descriptions in binary 
format. Its default file type is .FLB. 


Forms Management System (FMS) 


A set of software tools to simplify the development and maintenance of application 
programs involving formatted screen I/O to video terminals. 


Form Snapshot 


A representation of the current screen image; it is produced by the Form Driver at 
the request of a running application program, for subsequent printing. A form 
snapshot consists of background text, clear characters, field-marker characters, 
and any information displayed by the program or data entered by the operator. 


Form Tester 


The FMS component that provides a means of testing a form without first having 
to write an application program or put the form in a library. 


Form Upgrade Utility 


The FMS component that converts FMS Version 1 form descriptions into Version 2 
form descriptions. This utility can convert one form file to another form file or one 
form library to another form library. 


Hanging Cursor Position 


The place on the screen occupied by the cursor when it is one character position to 
the right of the end of a field. This is the initial position of the cursor for a right- 
justified field. 


Help User Action Routine 


A user-written routine activated when the operator presses HELP. A Help user 
action routine can be activated before or after help text or help forms are 
processed. 


Home Position 
The upper left corner of the screen. 


Indexed Field 


In a form, a field with multiple occurrences, all having the same name and being 
accessed by index value in addition to name. Indexed fields do not have to appear 
in a vertical or a horizontal direction. 
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insert Mode 


An input mode that causes typed characters to be placed at the current cursor 
location. Insert mode moves the cursor to the right, shifting other characters on 
the line or field to the right also. This mode is used by the Form Editor in Layout 
phase and by the Form Driver for field input. In the Form Driver, the mode that is 
the default for right-justified fields. Contrast with Overstrike Mode. 


Keypad Application Mode 


A mode in which keys on the terminal’s keypad generate special control sequences 
that can be used by application software. Contrast with Keypad Numeric Mode. 


Keypad Numeric Mode 


A mode in which keys on the terminal’s keypad generate the ASCII codes for the 
symbols printed on standard keycaps; the ENTER key generates the same code as 
the RETURN key on the main keyboard. In this mode, application software cannot 
distinguish between numeric characters typed on the main keyboard and numeric 
characters typed on the auxiliary keypad. Contrast with Keypad Application 
Mode. 


Left-Justified Attribute 


Line 


A field attribute specifying that the data entered is to be aligned with the leftmost 
data position; the remainder of the field may be filled with trailing zeros or spaces. 
See Zero Fill, Blank Fill, and Fill Character. 


The length from the leftmost position on the screen to the rightmost position on 
the screen along a given horizontal. The length of a line is fixed by the terminal 
hardware and is not related to the length of any character string that occupies 
part or all of the line. A line on a VT100-compatible terminal can be 80 or 132 
characters long. 


Named Data 


An ordered collection of constant information useful to the application program 
and associated with a specific form but not displayed on the screen. The Named 
Data for a form consists of constants, each of which can be accessed during run 
time by name or by its index. 


No Echo 


A field attribute indicating that any valid character typed by an operator or sen’ 
by an application program will not appear on the screen. The attribute is mos 
frequently used to keep passwords private. : 
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Order Phase 


In the Form Editor, a phase in which the order that fields are to be accessed by the 
Form Driver is established. | 


Operator 
The video terminal user who interacts with an FMS application program. 


Overstrike Mode 


In the Form Editor Layout phase, the mode that causes a character typed on the 
keyboard to replace the character at the current cursor position on the screen. 
Overstrike mode moves the cursor to the right but does not cause other characters 
on the line to be shifted to the right. 


In the Form Driver, the mode that is the default for left-justified fields. Contrast 
with Insert Mode. 


Pad 


To fill the empty data positions in a field with one or more occurrences of a charac- 
ter. See Fill Character, Blank Fill, and Zero Fill. 


Right-Justified Attribute 


A field attribute specifying that the data entered is to be aligned with the right- 
most data position; the remainder of the field may be filled with leading zeros or 
spaces. Note that data returned from a right-justified field to the application also 
appears right justified; the data may also have leading zeros or spaces. See Zero 
Fill, Blank Fill, and Fill Character. 


Screen 
The display surface of a video terminal. 


Screen Refresh 


To rewrite the information displayed on a video terminal by pressing CTRL/R. 
Screen refreshing restores to the screen information that may have been inter- 
rupted or distorted by a message or by noise on a communication line. 


Scroll 


To move upward or downward the lines of information that are displayed on the 
screen. See Scrolled Area. 


Scrolled Area 


On a form, an area consisting of identically formatted lines that can move upward 
or downward without affecting the remainder of the form and whose position on 
the screen is fixed. 
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Select Range 


An area that defines the extent of a video attribute assignment or other operation 
performed with the Form Editor in its Layout phase. 


Status Code 


A numeric value returned to the application program, indicating the success or 
failure of a Form Driver call. 


Supervisor Only Attribute 


A field attribute indicating that the field is considered to be display only when this 
attribute is enabled for a terminal. The application program enables and disables 
supervisor-only mode at run time. 


Terminal Control Area 
An area in memory set aside for a terminal to be used in an FMS application. 


Test Phase 


A Form Editor phase in which a form is displayed on the screen as it would appear 
in an application program. During the Test phase, data can be entered into fields 
to verify that the fields accept data as intended. 


Text Mode 


In the Form Editor Layout phase, the mode that allows creation and modification 
of background text in a form. Contrast with Field Mode. 


User Action Routine 


A routine associated with a particular field or form and that is invoked by FMS 
when the operator completes a field or a form by pressing a terminator key or by 
requesting help. 


Video Attributes 


Characteristics assigned to areas of a form, indicating which video features are to 
be activated. Examples of video attributes are bold, blink, reverse, and underline. 


Workspace 


An area in memory used by the Form Driver when it accesses a form; the work- 
space maintains context from one Form Driver call to the next for the same form. 
The workspace was called the impure area in earlier versions of FMS. 


Zero Fill Attribute 


A field attribute specifying that field values returned to the application program 
are to be padded with zeros. Contrast with Blank Fill Attribute. 
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index 


Advanced video option, 2—1, 3-1 
Alphanumeric strings, presenting in a 
form, 8-5 
ANSI_CRT, 2-1 
Application development cycle, 1—4 to 
1—10 
Application program 
compiling, 1-8 
linking, 1-10 
writing, 1-6 
Applications 
compiling, 6—2 
linking, 6—2 
running, 6—2 
Assign phase, 3—15 
Attributes . 
assigning field, 3-15, 3-22 
assigning form, 3—9, 3-19 
assigning indexing, 7-3 
autotab, 8-8 
Clear Character, 8-8 
Display Only, 8-8 
Fixed Decimal, 8-8 
FMS field, 8-8 
Must Fill, 8-9 
No Echo, 8-9 
Response Required, 3-16, 8-9 
Right Justify, 8-9 
Supervisor Only, 8-9 
Uppercase, 8-9 
Zero Fill, 8-9 
Zero Suppress, 8-9 


Autotab attribute, 8-8 
AVO, 2-1, 3-1 


BASIC, DCL command, 6—2 
Bold video attribute, assigning, 3-21 


Captions, writing, 8-3 

CENTER function, Form Editor, 3-12 

Character size, changing, 3-11 

Character width, changing, 3-12 

Check boxes, providing, 8—3 

Clear Character attribute, 3-23, 8-8 

COBOL data definition file, 1—4, 1-6 

Communication with operator, advice on, 
8-7 

Compiling an application, 1-8 

/CREATE qualifier, using, 4-1 

Current context, returning, 7-25 


Data 
assigning Named, 7-18 
punctuating in a form, 8-6 
Data lists, presenting in a form, 8-6 
Data presentation, 8—5 
DATATRIEVE domain definition file, 
1-4, 1-6 . 
DATE function, Form Editor, 3-20 
DEC_CRT, 3-1 
Default field name, 3—16 
Default field value, assigning, 3-16 
DEPOSIT form, 2—7, 3—4, 3—17 
description of, 3—4 
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Directory, obtaining of Form Library, 1-6, 
4-3 
Display Only attribute, 3-22, 8-8 
Double-size characters, 3—3, 3-11 
example of, 2-4 
Double-wide characters, 3-3, 3-12 
example of, 2—4 
DRAW function, Form Editor, 3-12 


Errors, recovering from in forms, 8-8 
Error status, returning from previous call, 
. 5-19 

Exit phase, 3-17, 3-24 


FAA. See Form Application Aids 
FDV$ATERM call, 5-7 
FDV$AWKSP call, 5-8 
FDV$CDISP call, 5-12 
FDV$DTERM call, 5-10, 5-19 
FDV$DWKSP call, 5-10 
FDV$GETAL call, 5-4 
FDV$GET call, 5—4, 5-13 
FDV$LCLOS call, 5-10 
FDV$LOPEN call, 5-9 
FDV$PFT call, 7-12 
FDV$PUT call, 5-16, 7-5 
FDV$PUTL call, 5-14 
FDV$PUTSC call, 7-12 
FDV$RETCX call, 7-25 
FDV$RETDI call, 7-18 
FDV$RETDN call, 7-18 
FDV$STAT call, 5-19 
FDV$WAIT call, 5-15 
FDV. See Form Driver 
FED. See Form Editor 
Field 

creating, 3-13 

example of, 2—4 

output value to a, 5-16 

requesting input for, 5-13 
Field attributes 

assigning, 3-15, 3-22, 3-23 

autotab, 8-8 

Clear Character, 3-23, 8-8 

Display Only, 3-22, 8-8 

Fixed Decimal, 3~23, 8-8 

FMS, 8-8 

Must Fill, 8-9 

No Echo, 8-9 

Response Required, 3-16, 8-9 

Right Justify, 3-22, 8-9 

Supervisor Only, 8-9 

Uppercase, 8-9 
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Zero Fill, 3-22, 8-9 
Zero Suppress, 3-22, 8-9 
Fields, indexing, 7-1 
Field value, assigning default, 3-16 
Fixed Decimal attribute, 3-23, 8-8 
example of, 2—7 
FLB. See Form Librarian 
FMS/DESCRIPTION, DCL command, 
4-3, 4-5 
FMS/EDIT, DCL command, 3-7, 3-19, 
3-24, 7-19, 7-23 
FMS/LIBRARY, DCL command, 4—1, 
7-8, 7-20 
FMS/VECTOR, DCL command, 7—26 
FMS Application, linking, 1-10 
FMS application development, 1—4 to 
1-10 
FMS documentation, reading path, 1-10, 
1-11 
FMS utilities, 1-2 
Form 
displaying on a screen, 5-12 
laying out. See Layout phase 
Form Application Aids, 1-4, 1-5 to 1-6 
Form attributes, assigning, 3-9, 3-19 
Form description, 1-6, 4-3 
interpreting, 4-3 
obtaining, 4-3 
translating to form, 1-3 
Form Driver, 1-3, 5-1 
control calls, 5-3 
FDV$ATERM call, 5-7 
FDV$AWKSP call, 5-8 
FDV$CDISP call, 5-12 
FDV$DTERM call, 5-10, 5-19 
FDV$DWKSP call, 5-10 
FDV$GETAL call, 5—4 
FDV$GET call, 5—4, 5-13 
FDV$LCLOS call, 5-10 
FDV$LOPEN call, 5-9 
FDV$PFT call, 7-12 
FDV$PUT call, 5-16, 7-5 
FDV$PUTL call, 5-14 
FDV$PUTSC call, 7-12 
FDV$RETCX call, 7-25 
FDV$RETDI call, 7-18 
FDV$RETDN call, 7-18 
FDV$STAT call, 5-19 
FDV$WAIT call, 5-15 
field-level calls, 5-3 
form-level calls, 5-3 
functional division of calls, 5-2 
string handling, 5—4 
utility calls, 5-3 


Form Editor, 1-2, 1-5, 3-6 
Assign phase, 3-15 
bold video attribute, 3-21 
CENTER function, 3-12 
DATE function, 3-20 
double-size character function, 3-11 
double-wide character function, 3—12 
DRAW function, 3-12 
Exit phase, 3-17, 3-24 
Form phase, 3-19 
Insert mode, 3-14 
Layout phase, 3-19 
Overstrike mode, 3—14 
REPEAT function, 3-20 
starting, 3-7, 3-19, 3-24 
Test phase, 3-17, 3-23 
underline video attribute, 3-15 
using, 3-6 
VIDEO function, 3-14 
Form Editor menu, 3-8 
Form image, obtaining, 4-5 
Form Language Translator, 1-3, 1-5 
Form Librarian, 1—3, 1-5 
using, 4-1 
Form libraries, obtaining directory listing 
of, 1-6 
Form Library, 1-5 
Form phase, 3-9, 3—19 
Forms 
advice on designing, 8-1 
creating, 1-5 
laying out, 3—19 
providing titles for, 8—2 
storing in a library, 1-5 
testing, 3-17 
Form Tester, 1-4, 1-5 
Form Translator. See Form Language 
Translator 


GETSTA subroutine, 5—19 
description of, 5-6 


Help, obtaining on-line, 2—2 

Help form, 2-3 

Help forms, creating, 3—24 

Help text, assigning, 3-17 
Highlighting, using in forms, 8-8 


/JIMAGE qualifier, using, 4-5 

INACCT subroutine, 5—11, 7-10 
description of, 5-6 

Indexing attribute, assigning, 7-3 

Indexing fields, 7-1 

Information, sorting, 8-2 


Input 
requesting from operator, 5-13 
waiting for, 5-15 
Insert mode, Form Editor, 3-14 
/INSERT qualifier, 7-8 
Instructions, providing, 8—4 


Keypad stickup, 3-6 


Languages, list of supported, 1-2 
Layout phase, 3-10, 3-19 
Library 

closing, 5-10 

opening, 5-9 
Library. See also Form Librarian 
Library file 

creating, 4-1 

obtaining a directory listing, 4-3 
Line, displaying on screen, 5—14 
Line draw function, using Form Editor, 

3-12 

LINK, DCL command, 6-2 
Listing, subset application, A—1 


MAKDEP subroutine, 5—16 
description of, 5-6 

Memory-resident forms, 1-6 

MENU form, 2-4, 3-2, 7-23 
description of, 3—2 

MENU subroutine, 5—11, 5-14 
description of, 5-6 

Message, displaying on screen, 5—14 

Messages, presenting in forms, 8-8 

Must Fill attribute, 8-9 


Named Data, 7-17 
returning by index, 7-18 
returning by name, 7-18 

No Echo attribute, 8-9 
example of, 2-9 


Ordered data, presenting in a form, 8-5 
Overstrike mode, Form: Editor, 3-14 


REGARRAY$, 7—10 
REGISTER form, 2—8, 7-2, 7-6, 7~19 
REPEAT function, Form Editor, 3-20 
/REPLACE qualifier, 7—20 
Response Required attribute, 3-5, 8-9 
assigning, 3-16 
example of, 2-6 
Reverse video, 3-3 


Right Justify attribute, 3-22, 8-9 


RUN, DCL command, 6—2 
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SAMP, 1-3 
listing of, A-1 
See also Sample Application 
SAMPCH.DAT, 2-10 
Sample Application, 1-3 to 1-4, 2—1 to 
2-10 
starting, 2-2 
SCRBAK subroutine, 7-16 
Screen layout, advice on, 8-7 
SCRFWD subroutine, 7-14 
Scrolled area 
altering current line, 7-12 
creating with Form Editor, 7—7 
output a data line to, 7-12 
Scrolling, 7-5 
example of, 2-8 
Scrolling backward, example of, 7-16 
Scrolling forward, example of, 7-14 
SET TERMINAL/INQUIRE, DCL 
command, 2-1, 3-1 
SHOW TERMINAL, DCL command, 
2-1, 3-1 
Source program, writing, 1-6 
SPACE$, VAX-11 BASIC function, 5-17 
Status line, 3-10 
returning from previous call, 5-19 
See also Layout phase status line 
STR$, VAX—11 BASIC function, 5-17 
SUBSET.BAS, 5-6 
See also Sample Application subset 
program, 5-6 
Subset application listing, A-1 
Subset program, 5—4 
description of, 5—4 
See also SUBSET.BAS 
Supervisor Only attribute, 8-9 
Supported languages, 1-2 


Terminal 
attaching, 5-7 
detaching, 5-10, 5-19 
setting up, 2-1, 3-1 
Terminal control area, 5—7 
Tester. See Form Tester 
Test phase, 3-17, 3-23 
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Titles, providing for forms, 8—2 
Translator. See Form Language 
Translator 


UARs, 1-5, 7-21 
compiling, 1-9 
compiling, linking, and running, 7—27 
creating a sample, 7—22 
field completion, 7-22 
function key, 7-22 
help, 7-22 
writing, 1-9 


-UAR vector module, 1-5, 1-9 


creating, 7-26 
Underline, Form Editor video attribute, 
3-15 
Uppercase attribute, 8-9 
User Action Routines, 1-5 
See also UARs 
Utilities, list of FMS, 1-2 


VAL, VAX-—11 BASIC function, 5-17 
VALID1 UAR, 7-23 
compiling, linking, and running, 7-27 
Video, reverse, 8—4 
Video attributes 
assigning, 3-14, 3-21 
assigning bold, 3-21 
assigning underline, 3-15 
VIDEO function, Form Editor, 3—14 
Video screen, advice on using, 8—5 
VT52, 2-1 
VUEACT subroutine, 5-18 
description of, 5-6 
VUEREG subroutine, 5—18, 7-4, 7-20 
description of, 5-6 


Workspace, 5-8 
attaching, 5-8 
detaching, 5—10 
WRITCH subroutine, 5-15 
description of, 5-6 


Zero Fill attribute, 3-22, 8~9 
Zero Suppress attribute, 3-22, 8-9 
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